mimesis 0.2.0

Generate 3D meshes from images using contour tracing and polygon extrusion.
Documentation

🖼️ Mimesis

Generate 3D meshes from images using contour tracing and polygon extrusion.

✨ Features

  • Remove background using the RMBG-1.4 model
  • Extracts binary mask from an image based on the alpha channel
  • Detects polygon contours using Theo Pavlidis' contour tracing algorithm
  • Smooths and simplifies the polygon
  • Triangulates the polygon using the Earcutr algorithm
  • Extrudes the 2D mesh into a 3D shape with configurable depth
  • Maps the original image onto the extruded mesh IV
  • Exports the result to a wavefront obj file
Step Description Image
1️⃣ Original Image Original
2️⃣ Binary Mask Mask
3️⃣ Polygon Contour (smoothed) Contour
4️⃣ Extruded 3D Mesh 3D
5️⃣ Vertex View Wireframe

Installation

cargo build --release

Usage

Basic Usage

# Process a single image

./mimesis -i texture.png -o output/


# Process with custom mask

./mimesis -i texture.png -m mask.png -o output/


# Batch process directory

./mimesis -i images/ -o output/

Configuration File

Generate a default configuration file:

./mimesis --generate-config -c config.json

Use configuration file:

./mimesis -c config.json

Command Line Options

Input/Output

  • -i, --input <PATH> - Input image file or directory
  • -m, --mask <PATH> - Optional binary mask image
  • -o, --output <PATH> - Output directory
  • -c, --config <PATH> - Configuration file path

Processing Parameters

  • --onnx-background-removal - Enable ONNX background removal
  • --onnx-model-path - Path to the ONXX model
  • --simplify-tolerance <FLOAT> - Polygon simplification tolerance (default: 10.0)
  • --smooth-iterations <INT> - Number of smoothing iterations (default: 1)
  • --extrude-height <FLOAT> - 3D extrusion height (default: 20.0)
  • --min-polygon-dimension <INT> - Minimum polygon size in pixels (default: 0)
  • --threshold <INT> - Binary mask threshold 0-255 (default: 128)
  • --mask-method <METHOD> - Mask generation method: alpha, luminance, red, green, blue (default: alpha)

Batch Processing

  • --include-patterns <PATTERNS> - File patterns to include (e.g., ".png,.jpg")
  • --exclude-patterns <PATTERNS> - File patterns to exclude
  • --workers <INT> - Number of parallel workers (default: 1)
  • --continue-on-error - Continue processing if some files fail

Output Options

  • --side-texture <PATH> - Custom side texture file
  • --back-texture <PATH> - Custom back texture file
  • --skip-intermediates - Skip saving intermediate files

Other

  • --generate-config - Generate default config file and exit
  • -v, --verbose - Verbose output
  • --benchmark - Benchmark output

Mask Generation Methods

When no mask is provided, the tool can auto-generate binary masks using:

  • Alpha - Uses alpha channel transparency (default)
  • Luminance - Uses brightness/luminance values
  • Red/Green/Blue - Uses individual color channels

Output Structure

For each processed image, the tool generates:

output/
├── textures/
│   ├── image_name.png      # Front texture
│   ├── side.png            # Side texture (if provided)
│   └── back.png            # Back texture (if provided)
├── image_name_0.obj        # 3D mesh file
├── image_name_0.mtl        # Material file

Batch Processing

When processing directories:

  1. All matching files are found using include/exclude patterns
  2. For each image, the tool looks for a corresponding mask file with _mask suffix
  3. If no mask is found, one is auto-generated
  4. Files with _mask in the name are automatically excluded from processing

Example batch structure:

input/
├── sprite1.png
├── sprite1_mask.png    # Optional custom mask
├── sprite2.png
└── character.jpg

Examples

Generate mesh with custom parameters

./mimesis \

  -i character.png \

  -o models/ \

  --extrude-height 30.0 \

  --simplify-tolerance 5.0 \

  --smooth-iterations 2 \

  --threshold 200 \

  --mask-method luminance

Batch process with configuration

# Generate config template

./mimesis --generate-config -c batch_config.yaml


# Edit config file, then run

./mimesis -c batch_config.yaml -i sprites/ -o output/

Process with custom textures

./mimesis \

  -i logo.png \

  -o output/ \

  --side-texture wood_texture.jpg \

  --back-texture metal_texture.jpg

Background removal

This feature allows you to run background removal on images using the RMBG-1.4 model.

Model

Usage

  1. Set the ONNX Runtime library path using the ORT_LIB_LOCATION environment variable:

Example (Windows):

set ORT_LIB_LOCATION=C:\path\to\onnxruntime.dll

Refer to this guide for details.

  1. Enable the feature in your Cargo run command:
cargo run --features background-remover

Supported Formats

Input Images

  • PNG, JPEG, BMP, TIFF, TGA
  • RGB and RGBA formats supported
  • Alpha channel used for mask generation when available

Output Formats

  • OBJ (Wavefront) mesh files
  • MTL (Material) files
  • PNG textures and visualizations

Configuration Files

  • JSON (.json)
  • TOML (.toml)

Performance Tips

  1. Simplification: Higher simplify_tolerance values create simpler meshes
  2. Smoothing: More iterations create smoother curves but increase processing time
  3. Minimum polygon size: Filter out small noise polygons
  4. Batch processing: Use --workers for parallel processing (TO BE IMPLEMENTED)
  5. Skip intermediates: Use --skip-intermediates to save disk space