Generate 3D meshes from images using contour tracing and polygon extrusion.
- 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 | |
| 2️⃣ | Binary Mask | |
| 3️⃣ | Polygon Contour (smoothed) | |
| 4️⃣ | Extruded 3D Mesh | |
| 5️⃣ | Vertex View |
cargo build --release# 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/Generate a default configuration file:
./mimesis --generate-config -c config.jsonUse configuration file:
./mimesis -c config.json-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
--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)
--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
--side-texture <PATH>- Custom side texture file--back-texture <PATH>- Custom back texture file--skip-intermediates- Skip saving intermediate files
--generate-config- Generate default config file and exit-v, --verbose- Verbose output--benchmark- Benchmark output
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
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
When processing directories:
- All matching files are found using include/exclude patterns
- For each image, the tool looks for a corresponding mask file with
_masksuffix - If no mask is found, one is auto-generated
- Files with
_maskin the name are automatically excluded from processing
Example batch structure:
input/
├── sprite1.png
├── sprite1_mask.png # Optional custom mask
├── sprite2.png
└── character.jpg
./mimesis \
-i character.png \
-o models/ \
--extrude-height 30.0 \
--simplify-tolerance 5.0 \
--smooth-iterations 2 \
--threshold 200 \
--mask-method luminance# Generate config template
./mimesis --generate-config -c batch_config.yaml
# Edit config file, then run
./mimesis -c batch_config.yaml -i sprites/ -o output/./mimesis \
-i logo.png \
-o output/ \
--side-texture wood_texture.jpg \
--back-texture metal_texture.jpgThis feature allows you to run background removal on images using the RMBG-1.4 model.
- Download the ONNX model here:
RMBG-1.4.onnx
- Set the ONNX Runtime library path using the ORT_LIB_LOCATION environment variable:
Example (Windows):
set ORT_LIB_LOCATION=C:\path\to\onnxruntime.dllRefer to this guide for details.
- Enable the feature in your Cargo run command:
cargo run --features background-remover- PNG, JPEG, BMP, TIFF, TGA
- RGB and RGBA formats supported
- Alpha channel used for mask generation when available
- OBJ (Wavefront) mesh files
- MTL (Material) files
- PNG textures and visualizations
- JSON (.json)
- TOML (.toml)
- Simplification: Higher
simplify_tolerancevalues create simpler meshes - Smoothing: More iterations create smoother curves but increase processing time
- Minimum polygon size: Filter out small noise polygons
- Batch processing: Use
--workersfor parallel processing (TO BE IMPLEMENTED) - Skip intermediates: Use
--skip-intermediatesto save disk space