Documentation

Everything you need to integrate XRNet into your projects

Select Your Platform

Choose a platform to see tailored SDK documentation.

Introduction

The XRNet SDK is a React-based library that enables you to integrate 3D model viewing and customization capabilities into your applications. Built on top of Three.js and React Three Fiber, it provides a powerful and flexible way to display interactive 3D content.

Key Features:

Interactive 3D model viewer with AR support
Customizable model editor
Model recommendation service integration
TypeScript support with full type definitions
Material-UI integration

Installation

Install the XRNet SDK via npm or yarn:

bash

npm install @xrnet/sdk

# or with yarn
yarn add @xrnet/sdk

# or with pnpm
pnpm add @xrnet/sdk

Peer Dependencies

Make sure you have the following peer dependencies installed:

bash

npm install react@^18.3.1 react-dom@^18.3.1 \
  @mui/material@^5.x @mui/icons-material@^5.x \
  @emotion/react@^11.x @emotion/styled@^11.x \
  react-query@^3.x

Quick Start

Get started with a basic 3D model viewer in just a few lines of code:

tsx

import React from 'react';
import { XRNetViewer } from '@xrnet/sdk';
import type { XRModel } from '@xrnet/sdk';

const App: React.FC = () => {
  const model: XRModel = {
    id: "model-123",
    name: "Office Chair",
    model_urls: {
      glb: "https://example.com/model.glb",
      usdz: "https://example.com/model.usdz",
      obj: "",
      fbx: "",
      gltf: "",
      stl: "",
      dae: ""
    },
    description: "A comfortable office chair",
    tags: ["furniture", "office"],
    createdAt: "2024-01-01",
    updatedAt: "2024-01-01"
  };

  const handleClose = () => {
    console.log('Viewer closed');
  };

  return (
    <XRNetViewer
      model={model}
      open={true}
      onClose={handleClose}
      title="3D Model Preview"
    />
  );
};

export default App;

XRNetViewer Component

The XRNetViewer component displays 3D models with interactive controls and AR support.

Props

Prop	Type	Required	Description
model	XRModel	Yes	The 3D model object to display
open	boolean	Yes	Controls viewer visibility
onClose	() => void	Yes	Callback when viewer is closed
title	string	No	Optional viewer title

Example

tsx

import React, { useState } from 'react';
import { XRNetViewer } from '@xrnet/sdk';
import type { XRModel } from '@xrnet/sdk';

const MyComponent: React.FC = () => {
  const [isOpen, setIsOpen] = useState<boolean>(false);

  const model: XRModel = {
    id: "123",
    name: "Modern Sofa",
    model_urls: {
      glb: "https://models.example.com/sofa.glb",
      usdz: "https://models.example.com/sofa.usdz",
      obj: "",
      fbx: "",
      gltf: "",
      stl: "",
      dae: ""
    },
    description: "Comfortable 3-seater sofa",
    tags: ["furniture", "living room"],
    createdAt: "2024-01-01",
    updatedAt: "2024-01-01"
  };

  const handleOpenViewer = () => {
    setIsOpen(true);
  };

  const handleCloseViewer = () => {
    setIsOpen(false);
  };

  return (
    <div>
      <button onClick={handleOpenViewer}>
        View 3D Model
      </button>
      
      <XRNetViewer
        model={model}
        open={isOpen}
        onClose={handleCloseViewer}
        title="Modern Sofa Preview"
      />
    </div>
  );
};

export default MyComponent;

XRNetEditor Component

The XRNetEditor component provides an interactive editor for customizing 3D models with real-time preview.

Props

Prop	Type	Required	Description
model	XRModel	Yes	The 3D model to edit
onChange	(model: XRModel) => void	Yes	Callback when model is modified

Example

tsx

import React, { useCallback } from 'react';
import { XRNetEditor } from '@xrnet/sdk';
import type { XRModel } from '@xrnet/sdk';

const ModelEditor: React.FC = () => {
  const handleModelChange = useCallback((updatedModel: XRModel) => {
    console.log('Model updated:', updatedModel);
    // Save to backend or update state
    // Example: saveModelToBackend(updatedModel);
  }, []);

  const model: XRModel = {
    id: "456",
    name: "Gaming Chair",
    model_urls: {
      glb: "https://models.example.com/chair.glb",
      usdz: "",
      obj: "",
      fbx: "",
      gltf: "",
      stl: "",
      dae: ""
    },
    description: "Ergonomic gaming chair",
    tags: ["furniture", "gaming"],
    createdAt: "2024-01-01",
    updatedAt: "2024-01-01"
  };

  return (
    <div>
      <XRNetEditor
        model={model}
        onChange={handleModelChange}
      />
    </div>
  );
};

export default ModelEditor;

React Hooks

useXrModelRecommendationService

A React Query hook for fetching recommended 3D models from the XRNet API.

tsx

import React from 'react';
import { useXrModelRecommendationService } from '@xrnet/sdk';
import type { XRModel } from '@xrnet/sdk';

const ModelGallery: React.FC = () => {
  const { data, isLoading, error } = useXrModelRecommendationService({
    start: 0,
    length: 10,
    search: "chair",
    order: "DESC"
  });

  if (isLoading) {
    return <div>Loading models...</div>;
  }

  if (error) {
    return <div>Error loading models</div>;
  }

  return (
    <div>
      <h2>Recommended Models ({data?.totalCount ?? 0})</h2>
      <div className="grid grid-cols-3 gap-4">
        {data?.data.map((model: XRModel) => (
          <div key={model.id}>
            <h3>{model.name}</h3>
            <p>{model.description}</p>
          </div>
        ))}
      </div>
    </div>
  );
};

export default ModelGallery;

Parameters

Parameter	Type	Description
start	number	Starting index for pagination
length	number	Number of items per page
search	string	Search query
order	"ASC" \| "DESC"	Sort order

TypeScript Types

The SDK includes comprehensive TypeScript definitions for type safety.

typescript

import type { 
  XRModel, 
  XRNetProperties, 
  ModelViewerProps,
  XRNetAPIKey,
  XRNetEnvironment 
} from '@xrnet/sdk';

// XRModel interface
interface XRModel {
  id: string;
  name: string;
  model_urls: {
    glb: string;
    obj: string;
    usdz: string;
    fbx: string;
    gltf: string;
    stl: string;
    dae: string;
    [key: string]: string;
  };
  properties?: XRNetProperties[];
  description: string;
  tags: string[] | null;
  createdAt: string;
  updatedAt: string;
  sub_categories?: SubCategory[];
}

// XRNetProperties interface
interface XRNetProperties {
  id: string;
  props: {
    cameraState?: {
      position: [number, number, number];
      target: [number, number, number];
      zoom: number;
      rotation: [number, number, number];
    };
    sections: { [key: string]: string };
    [key: string]: unknown;
  };
  thumbnail: string | null;
  description: string | null;
  createdAt: string;
  updatedAt: string;
}

// Environment enum
enum XRNetEnvironment {
  DEV = 'dev',
  PROD = 'prod'
}

Advanced Usage

Complete Integration Example

Here's a complete example showing how to integrate the SDK with model recommendations and viewer:

tsx

import React, { useState, useCallback } from 'react';
import { 
  XRNetViewer, 
  useXrModelRecommendationService 
} from '@xrnet/sdk';
import type { XRModel } from '@xrnet/sdk';

const ProductShowcase: React.FC = () => {
  const [selectedModel, setSelectedModel] = useState<XRModel | null>(null);
  const [viewerOpen, setViewerOpen] = useState<boolean>(false);

  // Fetch recommended models
  const { data, isLoading, error } = useXrModelRecommendationService({
    start: 0,
    length: 20,
    search: "furniture",
    order: "DESC"
  });

  const handleViewModel = useCallback((model: XRModel) => {
    setSelectedModel(model);
    setViewerOpen(true);
  }, []);

  const handleCloseViewer = useCallback(() => {
    setViewerOpen(false);
  }, []);

  if (isLoading) {
    return <div>Loading 3D models...</div>;
  }

  if (error) {
    return <div>Error loading models. Please try again.</div>;
  }

  return (
    <div>
      <h1>3D Product Gallery</h1>
      
      {/* Model Grid */}
      <div className="grid grid-cols-4 gap-6">
        {data?.data.map((model: XRModel) => (
          <div key={model.id} className="model-card">
            <img 
              src={model.properties?.[0]?.thumbnail ?? '/placeholder.jpg'} 
              alt={model.name}
            />
            <h3>{model.name}</h3>
            <p>{model.description}</p>
            <button 
              onClick={() => handleViewModel(model)}
              type="button"
            >
              View in 3D
            </button>
          </div>
        ))}
      </div>

      {/* 3D Viewer */}
      {selectedModel && (
        <XRNetViewer
          model={selectedModel}
          open={viewerOpen}
          onClose={handleCloseViewer}
          title={selectedModel.name}
        />
      )}
    </div>
  );
};

export default ProductShowcase;

Configuration

Configure the SDK with your API credentials and environment settings.

typescript

import { XRNetEnvironment } from '@xrnet/sdk';
import type { XRNetAPIKey } from '@xrnet/sdk';

// Set environment (default is PROD)
const environment: XRNetEnvironment = XRNetEnvironment.PROD;

// Configure API credentials
const apiKey: XRNetAPIKey = {
  publicKey: process.env.XRNET_PUBLIC_KEY || 'your-public-key',
  privateKey: process.env.XRNET_PRIVATE_KEY // optional
};

// Example configuration object
interface XRNetConfig {
  apiKey: XRNetAPIKey;
  environment: XRNetEnvironment;
  baseURL?: string;
}

const config: XRNetConfig = {
  apiKey,
  environment,
  baseURL: 'https://api.xrnet.tech/v1'
};

Support & Resources

Need Help?

If you have questions or need assistance, reach out to us:

Email: support@xrnet.tech
GitHub: github.com/xrnet
NPM Package: @xrnet/sdk