vectreal
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
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/viewerUsage
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
VectrealViewerusing themodelprop.
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
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 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
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:
- Clone the monorepo
- Install dependencies:
npm installoryarn install - Make your changes
- Build the package:
nx build vctrl/viewer - 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.