Mesh2Motion Documentation

Mesh2Motion allows you to import 3D models and automatically assign and export animations. The general workflow is:

1. Import: Upload a 3D model (currently supports only GLB/GLTF formats).
2. Skeleton Selection: Choose the skeleton type for your model.
3. Skeleton Modification: Adjust the skeleton to fit the model (optional testing available).
4. Animation Testing: Preview various animations on the model.
5. Export: Select desired animations and export the result (currently supports only GLB/GLTF formats).

The project uses Vitest for unit testing. Currently, tests are focused on the retargeting area, specifically covering various bone mapping permutations for BoneCategoryMapper (including Torso, Arm, Hand, Leg, Wing, Tail, and Unknown bones, as well as edge cases like empty arrays and case sensitivity).

To execute the test suite, run the following command in your terminal:

npm test

To deploy the survey processing system, you must use Cloudflare. Follow these steps to initialize the database, create the response schema, and deploy the worker:

1. Create a new D1 database in your Cloudflare account.
2. Retrieve the database UUID using npx wrangler d1 list.
3. Initialize the response storage table by executing the schema file against your database.
4. Deploy the Cloudflare Worker to process incoming survey responses.

You can run the project using Docker and Docker Compose to avoid modifying your local file system. Ensure Docker and Docker Compose are installed and running, then execute:

docker-compose up -d

Once running, the application is accessible at http://localhost:3000.

To run the application locally, ensure you have Node.js installed (version 24 is recommended). Navigate to the project root directory and execute the following commands to install dependencies and start the development server:

npm install
npm run dev

The Preview Generator is a browser-based tool used to create small animated .webm clip previews for the animation listing.

Workflow:

1. Start the web server locally using npm run dev.
2. Navigate to the Preview Generator URL: http://localhost:5173/preview-generator/index.html.
3. Select a 3D model from the drop-down menu (this pulls GLB files from the static/animations folder).
4. Rotate and position the 3D model as desired.
5. Press the record button.
6. Wait for all animations to finish playing and recording. A ZIP file containing the clips will be downloaded automatically once complete.
7. Move the resulting .webm files into the appropriate subfolder within static/animpreviews/ (organized by skeleton type).

The project uses Vite to compile TypeScript into browser-compatible files. To create a production-ready build, run:

npm run build

This command generates a dist folder containing all the files necessary to serve the application.

Testing configuration is managed in vitest.config.ts. The current configuration includes:

• Environment: jsdom (used for testing DOM-related code).
• Globals: Enabled (allows using describe, it, and expect without explicit imports in test files).
• Coverage: Uses the v8 provider with text, json, and html reporters.

You can run the Mesh2Motion application using Docker Compose. The service is configured to build from the local directory and maps the internal application port to host port 3000. The container is named mesh2motion-app and is set to restart automatically unless manually stopped.

services:
  mesh2motion-app:
    build: .
    container_name: mesh2motion-app
    ports:
      - "3000:5173"
    restart: unless-stopped

The Preview Generator relies on the following technologies and data structures:

• Model Source: GLB files are pulled from the static/animations folder. These files must contain both the skinned mesh and all associated animations.
• Recording Engine: Uses the standard browser MediaRecorder API.
• Compression: Uses the JSZIP JavaScript package to bundle recorded clips into a ZIP file.
• Canvas and Sizing: The canvas size is hard-coded in preview-generator.ts. Note that the display size in the generator is larger than the final output to facilitate easier positioning, but the application's CSS expects specific hard-coded dimensions for lazy loading and display.