React Body Map 3D SDK

Interactive 3D human body map React component with multi-language support, built with Three.js and React Three Fiber.

✨ Features

• 🎨 Full 3D interaction - Rotate, zoom, and pan
• 🌍 Multi-language - 6 languages supported
• 🎯 Clickable body parts - Interactive mesh selection
• ⚡ Smooth animations - Breathing effect and transitions
• 🎮 Intuitive controls - Mouse/touch gestures
• 🪶 Optimized - Efficient rendering with Three.js
• 📱 Responsive - Works on desktop and mobile

📦 Installation

npm install react-body-map-3d-sdk three @react-three/fiber @react-three/drei

🚀 Quick Start

import { BodyMap3D } from 'react-body-map-3d-sdk';
import 'react-body-map-3d-sdk/styles';

function App() {
  const handleSelect = (id, part) => {
    console.log('Selected:', part.name, part.category);
  };

  return (
    <BodyMap3D
      lang="en"
      onSelect={handleSelect}
      autoRotate={false}
    />
  );
}

📖 Props API

| Prop | Type | Default | Description | |------|------|---------|-------------| | lang | string | "en" | Language: en, fr, de, es, it, nl | | selectedPartId | number \| null | undefined | Controlled selection | | onSelect | (id, part) => void | undefined | Selection callback | | colors | object | See below | Color configuration | | showHeader | boolean | true | Show/hide header | | showControls | boolean | true | Show/hide control hints | | autoRotate | boolean | false | Auto-rotate model | | onLanguageChange | (lang) => void | undefined | Language change callback | | modelUrl | string | undefined | Custom 3D model (.glb) | | className | string | "" | Additional CSS class | | style | object | {} | Inline styles |

Colors Object

{
  default: "#8b8b8d",    // Default mesh color
  hover: "#a0a0a2",      // Hover state color
  selected: "#ff3b30"    // Selected state color
}

💡 Usage Examples

Controlled Mode

import { useState } from 'react';
import { BodyMap3D } from 'react-body-map-3d-sdk';

function ControlledExample() {
  const [selectedId, setSelectedId] = useState(null);
  const [language, setLanguage] = useState('en');

  return (
    <BodyMap3D
      lang={language}
      selectedPartId={selectedId}
      onSelect={(id, part) => {
        setSelectedId(id);
        console.log('Selected:', part);
      }}
      onLanguageChange={setLanguage}
    />
  );
}

Custom Colors

<BodyMap3D
  colors={{
    default: "#2c3e50",
    hover: "#34495e",
    selected: "#e74c3c"
  }}
/>

Auto-Rotate

<BodyMap3D
  autoRotate={true}
  showControls={false}
/>

Custom 3D Model

<BodyMap3D
  modelUrl="/models/human-body.glb"
  lang="fr"
/>

🎮 Controls

• Left Mouse / Touch: Rotate model
• Right Mouse / Two Fingers: Pan camera
• Scroll / Pinch: Zoom in/out
• Click: Select body part

📊 Data Utilities

import {
  get3DBodyParts,
  getBodyPartsByCategory,
  getBodyPartById,
  BODY_CATEGORIES
} from 'react-body-map-3d-sdk';

// Get all body parts
const parts = get3DBodyParts('en');

// Get parts by category
const legParts = getBodyPartsByCategory('en').legs;

// Find specific part
const part = getBodyPartById('en', 19); // Head

// Available categories
console.log(BODY_CATEGORIES);
// { HEAD: 'head', NECK: 'neck', TORSO: 'torso', ... }

🎨 Body Part Structure

Each body part includes:

{
  id: 19,
  name: "Head (ant.)",
  category: "head",
  meshNames: ["head", "skull", "face"],
  position: [0, 1.6, 0]  // 3D position for camera focus
}

🌍 Supported Languages

• 🇬🇧 English (en)
• 🇫🇷 French (fr)
• 🇩🇪 German (de)
• 🇪🇸 Spanish (es)
• 🇮🇹 Italian (it)
• 🇳🇱 Dutch (nl)

🎯 Body Categories

• HEAD - Head and face
• NECK - Neck region
• TORSO - Chest, back, abdomen
• ARMS - Upper and lower arms
• HANDS - Hands and fingers
• LEGS - Thighs, knees, calves
• FEET - Feet and toes

🔧 Advanced Usage

With Custom Model

To use your own 3D model:

1. Export model as .glb or .gltf
2. Ensure mesh names match body part meshNames
3. Pass model URL to component

<BodyMap3D
  modelUrl="/models/custom-body.glb"
/>

Mesh Naming Convention

Your 3D model meshes should follow this naming:

• head, skull, face
• neck_left, neck_right
• shoulder_left, shoulder_right
• bicep_left, bicep_right
• etc.

📱 Responsive Design

The component automatically adapts to different screen sizes:

<BodyMap3D
  style={{ height: '100vh' }}  // Full viewport height
/>

⚡ Performance Tips

1. Use production build for better performance
2. Limit auto-rotate on mobile devices
3. Optimize custom models (< 5MB recommended)
4. Use LOD (Level of Detail) for complex models

🆚 2D vs 3D Comparison

| Feature | 2D SDK | 3D SDK | |---------|--------|--------| | File Size | ~52KB | ~200KB | | Interaction | Click | Rotate, zoom, click | | Visual | SVG paths | 3D meshes | | Performance | Faster | Good | | Use Case | Simple selection | Immersive experience |

🔗 Related Packages

• react-body-map-sdk - 2D SVG version
• body-map-android - Native Android version

📄 License

MIT

🤝 Contributing

Contributions welcome! Please open an issue or PR.

🐛 Issues

Report issues at: GitHub Issues