vctrl/viewer

Table of Contents

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

Overview

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

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';
import { VectrealViewer } from '@vctrl/viewer';
import { ModelProvider } from '@vctrl/hooks/use-load-model';

function App() {
  return (
    <ModelProvider>
      <VectrealViewer />
    </ModelProvider>
  );
}

export default App;

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

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

Customize the OrbitControls with the controlsOptions prop:

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

Grid Options

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

Integration with vctrl/hooks

The VectrealViewer component is designed to work with the vctrl/hooks package. It uses the useModelContext hook to access the loaded model and loading state:

import { ModelProvider } from '@vctrl/hooks/use-load-model';
import { VectrealViewer } from '@vctrl/viewer';

function App() {
  return (
    <ModelProvider>
      <VectrealViewer />
      {/* Other components that use the model context */}
    </ModelProvider>
  );
}

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.