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

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.