@vctrl/viewer NPM

vctrl/viewer

This library is still undergoing heavy development until the first major version is released. This may lead to breaking changes in upcoming updates.

Overview

vctrl/viewer is a React component library for rendering and interacting with 3D models. It's part of the vectreal-core ecosystem and is designed to work seamlessly with the @vctrl/hooks package for model loading and management.

vctrl/viewer

Features

Easy-to-use React component for 3D model visualization
Integration with Three.js and React Three Fiber
Customizable camera, controls, and grid options
Support for various 3D model formats (via vctrl/hooks)
Responsive design with automatic resizing
Custom loading component support

Installation

To install the package, use npm or yarn:

npm install @vctrl/viewer
# or
yarn add @vctrl/viewer

Usage

Here's a basic example of how to use the VectrealViewer component:

import React from 'react';

// Use vctrl/hooks for loading a local model
import { useLoadModel } from '@vctrl/hooks/useLoadModel';

// You could also use the `useGLTF` hook from `@react-three/drei`
// import { useGLTF } from '@react-three/drei'

import { VectrealViewer } from '@vctrl/viewer';
import '@vctrl/viewer/css';

function App() {
  const { file } = useLoadModel();
  // const { scene: model } = useGLTF('/model.glb');

  return <VectrealViewer model={file.model} />;
}

export default App;

You must also import the CSS bundle for the viewer to work as expected. See the full example here.
You can also load any model supported by the react-three-drei loading hooks and pass it into the VectrealViewer using the model prop.

API Reference

`VectrealViewer` Component

The main component exported by this package.

Props

Customization

Camera Options

Perspective Camera docs

You can customize the camera by passing a cameraOptions prop:

<VectrealViewer
  cameraOptions={{
    initialCameraPosition: new Vector3(0, 5, 5),
    fov: 75,
    aspect: 1,
    near: 0.1,
    far: 1000,
  }}
/>

Controls Options

Orbit-controls props interface

Customize the controls based on OrbitControls with the controlsOptions prop:

<VectrealViewer
  controlsOptions={{
    maxPolarAngle: Math.PI / 2,
    autoRotate: true,
    controlsTimeout: 2000,
  }}
/>

Environment/Stage Options

Customize the @react-three/drei Stage and Environment components with the controlsOptions prop:

<VectrealViewer
  envOptions={{
    env: {
      preset: 'studio',
    },
    stage: {
      adjustCamera: 1.5,
    },
    backgroundColor: 'maroon',
  }}
/>

Grid Options

Grid props interface

Configure the grid display with the gridOptions prop:

<VectrealViewer
  gridOptions={{
    showGrid: true,
    cellSize: 0.5,
    sectionSize: 5,
    sectionColor: 'rgb(134, 73, 33)',
    cellColor: 'rgb(100, 100, 100)',
  }}
/>