Musclegram - 3D Human Muscle Visualization

Purpose

Musclegram is an interactive 3D web application that allows users to explore and learn about human muscles through an engaging 3D visualization. It provides detailed information about different muscle groups, their functions, and related exercises.

Functions

• Interactive 3D human model with selectable muscle groups
• Detailed muscle information in both English and Chinese
• Categorization of muscles (upper body, lower body, core, neck)
• Responsive sidebar with muscle details
• Smooth animations and transitions
• Mobile-friendly interface

Technical Stacks

• Frontend:
  • React 19 with TypeScript
  • Three.js with React Three Fiber and Drei
  • Tailwind CSS for styling
  • Radix UI components
  • Vite as build tool
• State Management: Zustand
• Animation: Framer Motion
• Icons: Lucide React
• Form Handling: React Hook Form
• Notifications: Sonner

Data Structures

Muscle Data

interface MuscleData {
  id: string;
  name_en: string;
  name_zh: string;
  position_3d?: {
    x: number;
    y: number;
    z: number;
  };
  mesh_data?: {
    type: string;
    radius?: number;
  };
  category: 'upper_body' | 'lower_body' | 'core' | 'neck';
  description?: string;
  exercises?: string[];
  origin?: string;
  insertion?: string;
  action?: string;
  nerve_supply?: string;
  blood_supply?: string;
}

Development

Getting Started

1. Prerequisites

   • Node.js (v18+)
   • npm or pnpm

2. Installation

   # Install dependencies
   pnpm install
   # or
   npm install

3. Environment Setup

   • Copy .env.example to .env and configure environment variables if needed

4. Running the Application

   # Start development server
   pnpm dev
   # or
   npm run dev

5. Building for Production

   # Build the application
   pnpm build
   
   # Preview the production build
   pnpm preview

Project Structure

src/
├── components/      # Reusable UI components
├── pages/          # Page components
├── hooks/          # Custom React hooks
├── lib/            # Utility functions
├── services/       # API and service integration
├── types/          # TypeScript type definitions
└── assets/         # Static assets

Key Features

1. 3D Model Interaction

   • Rotate, zoom, and pan the 3D model
   • Click on muscles to view details
   • Hover effects for better user experience

2. Responsive Design

   • Works on desktop and mobile devices
   • Adaptive layout for different screen sizes

3. Accessibility

   • Keyboard navigation support
   • ARIA labels and roles
   • High contrast mode

Usage Examples

Viewing Muscle Details

1. Click on any muscle in the 3D model
2. View detailed information in the sidebar
3. Navigate between different muscle groups using the category filters

Controlling the 3D Model

• Rotate: Click and drag with left mouse button
• Pan: Right-click and drag
• Zoom: Scroll wheel or pinch gesture on touch devices
• Reset View: Click the reset button in the corner

Testing

# Run tests
pnpm test

TODO

• Add more detailed muscle information
• Implement exercise demonstrations
• Add quiz mode for learning
• Support for different anatomical models
• Add user authentication for saving favorites
• Implement 3D printing support for physical models

References

• Three.js Documentation
• React Three Fiber Documentation
• Human Anatomy Reference

License

MIT