中文README

Attic Viewer

Attic Viewer is a web-based 3D viewer for robot models and scenes. Built on top of Three.js, it provides an intuitive interface for visualizing, editing, and simulating robots directly in the browser without any installation required.

Live Demo: http://viewer.osaerialrobot.top/

📝 This is a fork of fan-ziqi/robot_viewer, rewritten in TypeScript.

pre-release: https://atticlmr.github.io/attic_viewer/ support URDF2MJCF and MJCF2URDF, but need more feedback!

Key Features

• Format Support: URDF, Xacro, MJCF, USD
• Visualization: Visual/collision geometry, inertia tensors, center of mass, coordinate frames
• Interactive Controls: Drag joints in real-time
• Measurement Tools: Measure distances between joints and links
• Code Editor: Built-in CodeMirror editor with syntax highlighting
• Integrated Conversion Workflow: Convert between URDF and MJCF directly from the viewer
• Export Packages: Export converted models as ZIP packages with bundled assets and mesh/ directory layout
• Physics Simulation: Integrated MuJoCo runtime for MJCF models
• Web Deployment: GitHub Pages workflow for automatic build and deployment on main

What's New in v1.3.0

• Integrated the robot conversion workflow into the main viewer instead of keeping it as a standalone page
• Added viewer export flow for URDF/MJCF with packaged assets in ZIP format
• Normalized exported mesh assets into a dedicated mesh/ folder
• Improved URDF <-> MJCF conversion fidelity, including better handling of multi-joint bodies, default classes, actuators, and constraint-related metadata
• Fixed export behavior so converted downloads are packaged consistently for direct reuse
• Added GitHub Actions deployment for automatic GitHub Pages publishing on main
• Completed the current TypeScript cleanup pass across adapters, controllers, renderers, utilities, and tests

Getting Started

# Clone the repository
git clone https://github.com/Atticlmr/attic_viewer.git
cd attic_viewer

# Install dependencies
pnpm install

# Start development server
pnpm run dev

# Build for production
pnpm run build

# Run tests
pnpm test

# TypeScript type checking
pnpm typecheck

Development Commands

| Command | Description | |---------|-------------| | pnpm dev | Start development server | | pnpm build | Build for production | | pnpm preview | Preview production build | | pnpm test | Run unit tests | | pnpm test:watch | Run tests in watch mode | | pnpm test:coverage | Run tests with coverage | | pnpm typecheck | TypeScript type checking |

Project Structure

attic_viewer/
├── src/
│   ├── main.ts              # Application entry point
│   ├── app/
│   │   ├── App.ts           # Main application class
│   │   ├── AppState.ts      # Application state management
│   │   └── handlers/         # Event handlers
│   ├── adapters/             # Model format adapters (URDF, MJCF, USD, Xacro)
│   ├── controllers/          # Controllers (File, CodeEditor, Measurement)
│   ├── editor/              # Code editor (CodeMirror)
│   ├── loaders/             # Model loaders
│   ├── models/
│   │   └── UnifiedRobotModel.ts  # Unified robot model data interface
│   ├── renderer/            # Render managers (Scene, Visual, MuJoCo, etc.)
│   ├── ui/                  # UI components
│   ├── utils/               # Utilities
│   ├── views/               # View components (FileTree, ModelGraph)
│   └── test/                # Test setup
├── tsconfig.json            # TypeScript configuration
├── vitest.config.js         # Vitest configuration
└── vite.config.js           # Vite configuration

TypeScript Migration

This project has been migrated from JavaScript to TypeScript:

• Status: TypeScript migration baseline completed for the current codebase
• Build: Passing ✓
• Type Check: Passing ✓
• Tests: Passing (10 tests) ✓

Branches

• main - Stable release branch (from original repo)
• dev - Development branch with TypeScript rewrite

Contributing

We welcome contributions! Please read our contributing guidelines before submitting PRs.

License

Apache License 2.0 - see LICENSE file.

Open Source Attribution

This project is a TypeScript rewrite and derivative work based on fan-ziqi/robot_viewer. It also uses third-party open source software such as Three.js, Vite, CodeMirror, D3, urdf-loader, xacro-parser, and mujoco-js. See NOTICE for attribution details.