AutoForge

AutoForge is a Python tool for generating 3D printed layered models from an input image. Using a learned optimization strategy with a Gumbel softmax formulation, AutoForge assigns materials per layer and produces both a discretized composite image and a 3D-printable STL file. It also generates swap instructions to guide the printer through material changes during a multi-material print.

TLDR: It uses a picture to generate a 3D layer image that you can print with a 3d printer. Similar to Hueforge, but without the manual work.

!2.0_webui.png

Example

Input Image

Autoforge Output

Features

• Image-to-Model Conversion: Converts an input image into a layered model suitable for 3D printing.
• Learned Optimization: Optimizes per-pixel height and per-layer material assignments using PyTorch.
• Learned Heightmap: Optimizes the height of the layered model to create more detailed prints.
• Gumbel Softmax Sampling: Leverages the Gumbel softmax method to decide material assignments for each layer.
• FlatForge Mode: Generate separate STL files for each color, enabling face-down printing for smooth, resin-like finishes.
• STL File Generation: Exports an ASCII STL file based on the optimized height map.
• Swap Instructions: Generates clear swap instructions for changing materials during printing.
• Live Visualization: (Optional) Displays live composite images during the optimization process.
• Hueforge export: Outputs a project file that can be opened with hueforge.

Web UI: One-Click Install & Run

The easiest way to use AutoForge is the web UI, a local app with drag-and-drop image upload, a filament library, live sliders for adjusting colors after optimization, and pruning. No command-line arguments needed.

1. Clone this repository (or download and extract the ZIP from the green "Code" button on GitHub).
2. Install, from the project folder:

This installs uv (a fast Python package manager) if you don't already have it, installs all Python dependencies, and builds the web UI. You'll need Node.js installed for that last step, the installer will tell you if it's missing.

1. Run:

This starts the server and opens the web UI in your browser automatically (usually at http://localhost:8000).

To make some parts of the picture come out closer than the rest (a face, the eyes, lettering), click Focus in the image panel and paint over them; a slider sets how much more they count (2× to 100×, default 10×). After a run, the Differences view shows where the print strays furthest from the picture.

If HueForge is installed on the same computer, the web UI finds your HueForge personal filament library and offers to import it once, on its first start.

To find a filament you own without measuring it yourself, click Catalog in the filament library. It searches every filament on filamentcolors.xyz that has a measured TD (search by brand, color name, type or hex code; filter by type, brand or color family; or pick a color to see the closest matches first), and Add puts it straight into your library.

The web UI sends anonymous usage telemetry to the project via PostHog by default, to notify me of problems and any bugs. This includes crash reports (unhandled errors from both the browser frontend and the backend server, with the error type, message, and stack trace) so bugs can get fixed faster. No image data, filament data, or personal information is sent. To disable it, pass --no-telemetry (e.g. ./run_webui.sh --no-telemetry / run_webui.bat --no-telemetry), or set AUTOFORGE_WEBUI_TELEMETRY_ENABLED=false permanently in your environment.

1. Update to the latest release whenever you want, from the project folder:

This checks GitHub for a newer release and, if one exists, pulls it and reinstalls dependencies for you. Add --check to only check without applying it (e.g. ./update.sh --check).

GPU support

AutoForge runs on NVIDIA GPUs (CUDA), AMD GPUs (ROCm, Linux), Apple Silicon (MPS / Apple Metal) and, more slowly, on the CPU. The device is picked automatically in that order; override it with --device or the AUTOFORGE_DEVICE environment variable (e.g. AUTOFORGE_DEVICE=cpu).

install.sh installs the matching PyTorch build for you:

• NVIDIA: the default CUDA build; older (pre-Turing, e.g. GTX 10xx) cards automatically get the CUDA 12.6 build, the last one with kernels for them.
• AMD (Linux): detected through /dev/kfd and given the ROCm build. Consumer Radeon cards that ROCm doesn't officially list may need e.g. HSA_OVERRIDE_GFX_VERSION=10.3.0 (RX 6000) or 11.0.0 (RX 7000) set when running.
• Apple Silicon: the default macOS build already includes MPS.
• Anything else: run AUTOFORGE_TORCH_INDEX= ./install.sh, e.g. https://download.pytorch.org/whl/cpu. ./update.sh keeps whichever build was installed.

Manual Installation (CLI only)

If you just want the command-line tool (no web UI), install the current version from PyPI:

pip install -U autoforge

If you have problems running the code on your gpu, please refer to the Pytorch Homepage for help. \ CUDA, ROCm, and MPS (Apple Metal) are supported, but you need to install the correct version of pytorch for your system.

Usage

The script is run from the command line and accepts several arguments. Below is an example command:

Note: You will need Hueforge installed to export your filament CSV.

To get your CSV file, simply go to the "Filaments" menu in Hueforge, click the export button, select your filaments, and export them as a CSV file.

autoforge --input_image path/to/input_image.jpg --csv_file path/to/materials.csv

We also support json files. If you want to use your personal Hueforge library (found in %APPDATA%\HueForge\Filaments\personal_library.json) you can run the command with:

autoforge --input_image path/to/input_image.jpg --json_file %APPDATA%\HueForge\Filaments\personal_library.json

If you want to limit the amount of colors the program can use, you can set these as command line arguments. \

For Example: 8 colors and a maximum of 20 swaps:

autoforge --input_image path/to/input_image.jpg --csv_file path/to/materials.csv --pruning_max_colors 8 --pruning_max_swaps 20

FlatForge Mode

To use FlatForge mode for smooth, face-down printing:

autoforge --input_image path/to/input_image.jpg --csv_file path/to/materials.csv --flatforge --pruning_max_colors 4 --cap_layers 2

This will generate separate STL files for each color, allowing you to print face-down on the build plate for a smooth finish. With --pruning_max_colors 4, you'll get 2 colored materials + 1 clear filament + 1 background = 4 total filaments (perfect for a 4-slot AMS).

Command Line Arguments

• --config (Optional) Path to a configuration file with the settings.

• --input_image (Required) Path to the input image.
• --csv_file Path to the CSV file containing material data. The CSV should include columns for the brand, name, color (hex code), and TD values.
• --json_file Path to the json file containing material data.

• --output_folder Folder where output files will be saved (default: output).
• --iterations Number of optimization iterations (default: 2000).
• --warmup_fraction Fraction of iterations for keeping the tau at the initial value (default: 0.25).
• --learning_rate_warmup_fraction Fraction of iterations that the learning rate is increasing (warmup) (default: 0.25).
• --init_tau Initial tau value for Gumbel-Softmax (default: 1.0).
• --final_tau Final tau value for the Gumbel-Softmax formulation (default: 0.01).
• --learning_rate Learning rate for optimization (default: 0.015).
• --layer_height Layer thickness in millimeters (default: 0.04).
• --max_layers Maximum number of layers (default: 75).

• --min_layers Minimum number of layers (default: 0). Used to limit height of pruning.
• --background_height Height of the background in millimeters (default: 0.24).

• --background_color Background color in hexadecimal format (default: #000000 aka Black).

• --visualize enable live visualization of the composite image during optimization (default: True).
• --stl_output_size Size of the longest dimension of the output STL file in millimeters (default: 200).
• --processing_reduction_factor Reduction factor for the processing size compared to the output size (default: 2 - half resolution).
• --nozzle_diameter Diameter of the printer nozzle in millimeters (default: 0.4).

• --early_stopping Number of steps without improvement before stopping (default: 10000).
• --priority_mask (Optional) Path to a greyscale image the size of the input that marks the parts that matter most: white areas are matched more closely, black areas still count, just less.
• --priority_mask_strength How many times more a white pixel of --priority_mask counts than a black one (default: 10; must be at least 1). Raise it if the marked areas still come out off, lower it for a gentler nudge.

• --flatforge Enable FlatForge mode to generate separate STL files for each color (default: False).

• --cap_layers Number of complete transparent/clear layers to add on top in FlatForge mode (default: 0).

• --perform_pruning Perform pruning after optimization (default: True).

• --fast_pruning Perform pruning in chunks. 10-15x speedup compared to accurate method (default: False).
• --fast_pruning_percent Size of fast pruning chunks in percent (default: 0.5) (50%).
• --pruning_max_colors Max number of colors allowed after pruning (default: 100).

• --pruning_max_swaps Max number of swaps allowed after pruning (default: 100).
• --pruning_max_layer Max number of layers allowed after pruning (default: 75).
• --random_seed Random seed for reproducibility (default: 0 (disabled)).
• --device Torch device to run on, e.g. cuda, cuda:1, mps, cpu. Defaults to auto-detection: CUDA/ROCm first, then Apple Metal (MPS), then CPU. Can also be set with the AUTOFORGE_DEVICE environment variable.
• --mps Deprecated — Apple Metal is now detected automatically, so this flag is no longer needed. It still works, and forces MPS on a machine that also exposes a CUDA GPU; prefer --device mps.
• --no-spike-removal Disable spike removal for the final STL (not recommended).

• --tensorboard Flag to enable TensorBoard logging.
• --run_name (Optional) Name of the run used for TensorBoard logging.
• --num_init_rounds Number of rounds to choose the starting height map from (default: 1 - extra rounds are currently deterministic and don't add variety, so they only cost startup time).
• --num_init_cluster_layers Number of layers to cluster the image into (default: -1).
• --disable_visualization_for_gradio Simple switch to disable the matplotlib render window for gradio rendering (default: 0).
• --best_of Run the entire program multiple times and output the best result (default: 1)

Outputs

After running, the following files will be created in your specified output folder:

Traditional Mode:

• Discrete Composite Image: final_model.png
• STL File: final_model.stl
• Hueforge Project File: project_file.hfp
• Swap Instructions: swap_instructions.txt

• Discrete Composite Image: final_model.png
• Separate STL files for each color: One STL per material (e.g., BrandName_ColorName_HEXCODE.stl)
• Clear/Transparent STL: Uses the most transparent material from your library
• Background STL: Background_HEXCODE.stl
• Optional Cap Layer STL: Cap_MaterialName_HEXCODE.stl (if --cap_layers > 0)

Docker

The repository includes a Docker setup that builds the web UI, starts it automatically and serves it on http://localhost:8000. There is one compose file per kind of hardware; the first build takes a while, since it downloads PyTorch.

| Hardware | Compose file | Image | | --- | --- | --- | | NVIDIA GPU (Linux, Windows) | docker-compose.yml | autoforge-webui:latest | | AMD GPU (Linux, x86_64) | docker-compose.rocm.yml | autoforge-webui:rocm | | CPU only, and macOS (Intel and Apple Silicon) | docker-compose.cpu.yml | autoforge-webui:cpu |

Docker Compose 2.24 or newer is required. To check which device the running web UI uses, open http://localhost:8000/api/system/device: it lists cuda:0 (NVIDIA and AMD alike) when the GPU is visible inside the container, or only cpu when it is not.

NVIDIA

1. Install the NVIDIA driver and the NVIDIA Container Toolkit, then restart Docker. On Windows, Docker Desktop with the WSL 2 backend already includes GPU support; only the NVIDIA driver is needed.
2. Start AutoForge:

docker compose up -d --build

Older cards (GTX 10xx and other pre-Turing GPUs) need the CUDA 12.6 build of PyTorch, since the default build no longer has kernels for them:

TORCH_INDEX_URL=https://download.pytorch.org/whl/cu126 docker compose up -d --build

AMD

1. Linux only. The host needs the amdgpu kernel driver (included in current kernels); /dev/kfd must exist. The ROCm runtime itself ships inside the image, so ROCm does not need to be installed on the host.
2. Start AutoForge:

docker compose -f docker-compose.rocm.yml up -d --build

Consumer Radeon cards that ROCm doesn't officially list often need a GFX version override. Uncomment the environment block in docker-compose.rocm.yml and set HSA_OVERRIDE_GFX_VERSION to 10.3.0 for RDNA2 (RX 6000) or 11.0.0 for RDNA3 (RX 7000), then run the command again. If optimization fails with a Triton compilation error, add AUTOFORGE_TRITON: "off" to the same block to use the plain PyTorch code path.

AMD GPUs aren't supported by Docker on Windows or macOS; use the CPU image there.

Apple Silicon (MPS)

Docker containers on macOS run in a Linux VM with no access to Apple Metal, so the GPU cannot be used from Docker on a Mac. You have two options:

• Use the GPU: install AutoForge natively with ./install.sh and start it with ./run_webui.sh. The macOS build of PyTorch includes MPS, and AutoForge picks it automatically.
• Use Docker (CPU only):

docker compose -f docker-compose.cpu.yml up -d --build

CPU only

Works on any machine with Docker, but optimization is much slower than on a GPU:

docker compose -f docker-compose.cpu.yml up -d --build

Everyday use

The commands below use the NVIDIA compose file; add -f docker-compose.rocm.yml or -f docker-compose.cpu.yml for the other images.

| Task | Command | | --- | --- | | Show the logs | docker compose logs -f | | Stop | docker compose down | | Update to a newer version | git pull && docker compose up -d --build | | Use another port | WEBUI_PORT=9000 docker compose up -d | | Disable telemetry | AUTOFORGE_WEBUI_TELEMETRY_ENABLED=false docker compose up -d |

All the images start a container named autoforge, so stop the running one with its own compose file before switching to another.

Your projects, uploaded images, filament library and downloaded models are kept in the autoforge-data Docker volume, which survives restarts, updates and switching between the images. docker compose down -v deletes it along with the container.

To use your HueForge filament library, uncomment the HueForge lines in docker-compose.yml (the AUTOFORGE_WEBUI_HUEFORGE_LIBRARY variable and the volume mount) and point the mount at the folder containing personal_library.json.

Command-line tool

The autoforge CLI is included in every image. Mount the folder with your image and filament CSV into the container and run it from there; results are written into that folder:

# NVIDIA
docker run --rm --gpus all -v "$PWD:/work" -w /work autoforge-webui:latest \
    autoforge --input_image input.jpg --csv_file materials.csv --output_folder output

AMD
docker run --rm --device /dev/kfd --device /dev/dri --group-add video --group-add render \
    -v "$PWD:/work" -w /work autoforge-webui:rocm \
    autoforge --input_image input.jpg --csv_file materials.csv --output_folder output
CPU / macOS
docker run --rm -v "$PWD:/work" -w /work autoforge-webui:cpu \
    autoforge --input_image input.jpg --csv_file materials.csv --output_folder output

You can now run Autoforge for free in your browser thanks to Huggingface space support.

Development

To have a "nightly" version of the repository or have live updating changes during development please do the following:

git clone https://github.com/hvoss-techfak/AutoForge.git
cd AutoForge
conda create -n forge python=3.11
conda activate forge
pip install -e .

To refresh the bundled filamentcolors.xyz catalog (src/autoforge/data/filamentcolors_catalog.json) before a release, run ./generate_filamentcolors_library.sh. It downloads the whole catalog once, pausing 2 seconds between pages (--delay sets the pause; requests are never less than 1 second apart), and keeps only the filaments that have a TD.

If the installed pytorch version has no cuda support execute the following:

conda activate forge
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Known Bugs

• The optimizer can sometimes get stuck in a local minimum. If this happens, try running the optimization again with different settings.

License

AutoForge © 2025 by Hendric Voss is licensed under CC BY-NC-SA 4.0. The software is provided as-is and comes with no warranty or guarantee of support.

The above license applies to the software itself. How you use the generated files and prints is entirely up to you. If you want to print them for your friends or family, that's great. If you want to sell them, that's fine by me too.

From a licensing standpoint, this means that the prints you create are entirely subject to the MIT License, and you can do whatever you like with them. The only thing the MIT License does not give you is a warranty, and it also frees me from any liability with regard to your 3D prints. Otherwise, do whatever you like.

I would love to see what you have done with the software, so it would be great if you could send me a link to your work (even if it's just for selling). However, this is not necessary if you do not want to.

Acknowledgements

First and foremost:

• Hueforge for providing the inspiration for this project.

• filamentcolors.xyz and its community for the measured filament swatches and TD values in the web UI's filament catalog.

• PyTorch
• Optax
• OpenCV
• Matplotlib
• Pandas
• TQDM
• ConfigArgParse

Happy printing!