react-3d-model-viewer

A shadcn/ui styled 3D model viewer component for React with annotation, search and highlight support.

Features

• 3D Model Viewing: Load GLB/GLTF models with orbit controls
• Annotation System: Add, edit, delete annotations on 3D models
• Structure Search: Search and highlight anatomy structures
• Demo Model: Built-in skull anatomy demo model
• Comments: Add comments to annotations
• Responsive Design: Works with shadcn/ui styling

Installation

npm install react-3d-model-viewer

Peer Dependencies

npm install react react-dom three @react-three/fiber @react-three/drei

Quick Start

import { CompleteModelViewer } from 'react-3d-model-viewer'

export default function App() {
  return (
    <div className="h-[600px]">
      <CompleteModelViewer
        modelUrl="/models/skull.glb"
        structuresList={['Cranium', 'Frontal Bone', 'Temporal Bone']}
        showSearchBar={true}
      />
    </div>
  )
}

Usage

Basic Usage (Demo Model)

import { CompleteModelViewer } from 'react-3d-model-viewer'

function App() {
  return <CompleteModelViewer />
}

With Custom GLB Model

import { CompleteModelViewer } from 'react-3d-model-viewer'

function App() {
  return (
    <CompleteModelViewer
      modelUrl="/models/anatomy.glb"
      showSearchBar={true}
      structuresList={['Skull', 'Mandible', 'Spine']}
    />
  )
}

With Annotations

import { CompleteModelViewer, type Annotation } from 'react-3d-model-viewer'

const initialAnnotations: Annotation[] = [
  {
    id: '1',
    structureName: 'Cranium',
    position: { x: 0, y: 0.8, z: 0 },
    label: 'Skull',
    color: '#ff6b6b',
  },
]

function App() {
  return (
    <CompleteModelViewer
      modelUrl="/models/skull.glb"
      initialAnnotations={initialAnnotations}
      onSaveAnnotation={(data) => console.log('Save:', data)}
      onDeleteAnnotation={(ann) => console.log('Delete:', ann)}
    />
  )
}

Using Individual Components

import { ModelViewer } from 'react-3d-model-viewer/ModelViewer'

function App() {
  return (
    <ModelViewer
      modelUrl="/models/skull.glb"
      annotations={[]}
      highlightedStructures={[]}
      onAnnotationClick={(ann) => console.log(ann)}
      onModelPartClick={(mesh, point) => console.log(mesh, point)}
    />
  )
}

API Reference

CompleteModelViewer

| Prop | Type | Default | Description | |------|------|---------|-------------| | modelUrl | string | - | GLB model URL (empty shows demo) | | initialAnnotations | Annotation[] | [] | Initial annotation list | | showSearchBar | boolean | true | Show/hide search bar | | structuresList | string[] | [] | Structure names for search | | currentUserId | string | - | Current user ID for comments | | onSaveAnnotation | function | - | Callback when annotation saved | | onDeleteAnnotation | function | - | Callback when annotation deleted | | onAddComment | function | - | Callback when comment added | | onModelPartClick | function | - | Callback when model part clicked | | onHighlightChange | function | - | Callback when highlight changes |

ModelViewer

| Prop | Type | Default | Description | |------|------|---------|-------------| | modelUrl | string | - | GLB model URL | | annotations | Annotation[] | [] | Annotation list | | highlightedStructures | HighlightedStructure[] | [] | Structures to highlight | | selectedAnnotationId | string | - | Currently selected annotation | | showGrid | boolean | true | Show/hide grid | | backgroundColor | string | #1a1a2e | Canvas background |

AnnotationPanel

| Prop | Type | Default | Description | |------|------|---------|-------------| | annotation | Annotation | - | Current annotation | | isCreating | boolean | - | Creating new annotation mode | | newPosition | Position3D | - | New annotation position | | onSave | function | - | Save callback | | onDelete | function | - | Delete callback | | onAddComment | function | - | Add comment callback |

SearchBar

| Prop | Type | Default | Description | |------|------|---------|-------------| | structuresList | string[] | - | Structure names | | onSearchResults | function | - | Search results callback | | isSearching | boolean | - | Loading state | | placeholder | string | - | Placeholder text |

Types

interface Annotation {
  id: string
  structureName: string
  position: Position3D
  label?: string | null
  description?: string | null
  color: string
  meshName?: string | null
  comments?: Comment[]
}

interface Position3D {
  x: number
  y: number
  z: number
}

interface HighlightedStructure {
  meshName?: string
  structureName: string
  color?: string
}

Styling

This component uses Tailwind CSS classes. Make sure your project has Tailwind configured:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Add the content paths to your tailwind.config.js:

module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  // ... rest of config
}

License

MIT