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.

Table of Contents

• vctrl/viewer
  • Overview
  • Table of Contents
  • Features
  • Installation
  • Usage
  • API Reference
    • VectrealViewer Component
    • Props
  • Customization
    • Camera Options
    • Controls Options
    • Environment/Stage Options
    • Grid Options
  • Development
  • License
  • Contributing
  • Support

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

Prop	Type	Description
model	Object3D	(Optional when using `use-load-model` context) The 3D model to display
className	string	(Optional) Additional CSS classes for the viewer container
cameraOptions	CameraProps	(Optional) Configuration for the camera
controlsOptions	ControlsProps	(Optional) Configuration for the OrbitControls
envOptions	EnvProps	(Optional) Configuration for the Stage and Environment Component
gridOptions	GridProps	(Optional) Configuration for the grid
loader	() => JSX.Element	(Optional) Custom loading component

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

• Stage props interface
• Environment props interface

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)',
  }}
/>

Development

This package is part of a monorepo workspace managed with Nx. To contribute or modify the package:

1. Clone the monorepo
2. Install dependencies: npm install or yarn install
3. Make your changes
4. Build the package: nx build vctrl/viewer
5. Test your changes: nx test vctrl/viewer

License

Please refer to the LICENSE file in the package root for licensing information.

Contributing

Contributions are welcome! Please read the contributing guidelines in the vectreal-core monorepo before submitting pull requests.

Support

For issues, feature requests, or questions, please file an issue in the GitHub repository.