autoforge 2.1.0__tar.gz → 2.2.0__tar.gz

{autoforge-2.1.0 → autoforge-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AutoForge
-Version: 2.1.0
+Version: 2.2.0
 Summary: AutoForge - 3D color prints made easy
 Author-email: Hendric Voss <hvoss@techfak.uni-bielefeld.de>
 License: CC BY-NC-SA 4.0
@@ -93,6 +93,7 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
    - Windows: double-click `run_webui.bat`
 
    This starts the server and opens the web UI in your browser automatically (usually at `http://localhost:8000`).
+   It only listens on this computer by default, since the web UI has no login. To open it from other devices on your network, start it with `WEBUI_HOST=0.0.0.0 ./run_webui.sh` (Windows: `set WEBUI_HOST=0.0.0.0` before `run_webui.bat`). Open it by IP address or by this computer's name; any other name (for example one from a reverse proxy) has to be listed in `AUTOFORGE_WEBUI_ALLOWED_HOSTS` (comma separated).
 
    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.
 
@@ -100,7 +101,7 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
 
    To find a filament you own without measuring it yourself, click **Catalog** in the filament library. It searches every filament on [filamentcolors.xyz](https://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](https://posthog.com/) 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.
+   The web UI sends anonymous usage telemetry to the project via [PostHog](https://posthog.com/) 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 other personal information is sent, except that error messages and stack traces can contain file paths (the backend replaces your home folder in them with `~`, so your user name isn't sent from there; the browser's own stack traces only name the app's script files). 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.
 
 4. **Update to the latest release** whenever you want, from the project folder:
    - Linux/macOS: `./update.sh`
@@ -108,8 +109,17 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
 
    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`).
 
-If you have problems running the code on your GPU, please refer to the [Pytorch Homepage](https://pytorch.org/) for help. \
-CUDA, ROCm, and MPS (Apple Metal) are supported, but you need to install the correct version of pytorch for your system — `install.sh`/`install.bat` install whatever `uv sync` resolves by default, so swap in a GPU-specific PyTorch build afterwards if you need one. (`install.sh` handles older NVIDIA GPUs automatically, see below.)
+### 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=<PyTorch wheel index> ./install.sh`, e.g. `https://download.pytorch.org/whl/cpu`. `./update.sh` keeps whichever build was installed.
+
+If the fused GPU kernels (Triton) cause trouble on your GPU, `AUTOFORGE_TRITON=off` switches to the plain PyTorch code path. For other GPU problems, see the [PyTorch homepage](https://pytorch.org/).
 
 ## Manual Installation (CLI only)
 
@@ -184,7 +194,7 @@ This will generate separate STL files for each color, allowing you to print face
 - `--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).  
   **Note:** Details smaller than half this value will be ignored.
-- `--early_stopping` Number of steps without improvement before stopping (default: 10000).
+- `--early_stopping` Number of steps without improvement before stopping (default: 3000).
 - `--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.
 
@@ -234,9 +244,96 @@ After running, the following files will be created in your specified output fold
   
   *Note:* FlatForge generates multiple STL files that align perfectly when loaded together in your slicer, creating a solid rectangular print with each color as a separate object.
 
-## You can now run Autoforge for free in your browser thanks to [Huggingface space support](https://huggingface.co/spaces/hvoss-techfak/Autoforge).
-This includes the option to run it locally if you have a powerful pc and don't want to limit yourself to the Huggingface computing limits. \
-For this simply go to the [Huggingface](https://huggingface.co/spaces/hvoss-techfak/Autoforge) space and pull the docker container for this project (upper right corner -> three dots -> "run locally")
+## 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html), 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:
+   ```bash
+   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:
+```bash
+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:
+   ```bash
+   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):**
+  ```bash
+  docker compose -f docker-compose.cpu.yml up -d --build
+  ```
+  This builds a native arm64 image. In Docker Desktop, raise the memory limit (Settings → Resources) if large images fail with out-of-memory errors.
+
+### CPU only
+
+Works on any machine with Docker, but optimization is much slower than on a GPU:
+```bash
+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:
+```bash
+# 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
+```
+The container runs as root, so on Linux the output files belong to root; `sudo chown -R "$USER" output` makes them yours again.
 
 ## Development
 

{autoforge-2.1.0 → autoforge-2.2.0}/README.md

@@ -56,6 +56,7 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
    - Windows: double-click `run_webui.bat`
 
    This starts the server and opens the web UI in your browser automatically (usually at `http://localhost:8000`).
+   It only listens on this computer by default, since the web UI has no login. To open it from other devices on your network, start it with `WEBUI_HOST=0.0.0.0 ./run_webui.sh` (Windows: `set WEBUI_HOST=0.0.0.0` before `run_webui.bat`). Open it by IP address or by this computer's name; any other name (for example one from a reverse proxy) has to be listed in `AUTOFORGE_WEBUI_ALLOWED_HOSTS` (comma separated).
 
    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.
 
@@ -63,7 +64,7 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
 
    To find a filament you own without measuring it yourself, click **Catalog** in the filament library. It searches every filament on [filamentcolors.xyz](https://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](https://posthog.com/) 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.
+   The web UI sends anonymous usage telemetry to the project via [PostHog](https://posthog.com/) 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 other personal information is sent, except that error messages and stack traces can contain file paths (the backend replaces your home folder in them with `~`, so your user name isn't sent from there; the browser's own stack traces only name the app's script files). 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.
 
 4. **Update to the latest release** whenever you want, from the project folder:
    - Linux/macOS: `./update.sh`
@@ -71,8 +72,17 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
 
    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`).
 
-If you have problems running the code on your GPU, please refer to the [Pytorch Homepage](https://pytorch.org/) for help. \
-CUDA, ROCm, and MPS (Apple Metal) are supported, but you need to install the correct version of pytorch for your system — `install.sh`/`install.bat` install whatever `uv sync` resolves by default, so swap in a GPU-specific PyTorch build afterwards if you need one. (`install.sh` handles older NVIDIA GPUs automatically, see below.)
+### 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=<PyTorch wheel index> ./install.sh`, e.g. `https://download.pytorch.org/whl/cpu`. `./update.sh` keeps whichever build was installed.
+
+If the fused GPU kernels (Triton) cause trouble on your GPU, `AUTOFORGE_TRITON=off` switches to the plain PyTorch code path. For other GPU problems, see the [PyTorch homepage](https://pytorch.org/).
 
 ## Manual Installation (CLI only)
 
@@ -147,7 +157,7 @@ This will generate separate STL files for each color, allowing you to print face
 - `--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).  
   **Note:** Details smaller than half this value will be ignored.
-- `--early_stopping` Number of steps without improvement before stopping (default: 10000).
+- `--early_stopping` Number of steps without improvement before stopping (default: 3000).
 - `--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.
 
@@ -197,9 +207,96 @@ After running, the following files will be created in your specified output fold
   
   *Note:* FlatForge generates multiple STL files that align perfectly when loaded together in your slicer, creating a solid rectangular print with each color as a separate object.
 
-## You can now run Autoforge for free in your browser thanks to [Huggingface space support](https://huggingface.co/spaces/hvoss-techfak/Autoforge).
-This includes the option to run it locally if you have a powerful pc and don't want to limit yourself to the Huggingface computing limits. \
-For this simply go to the [Huggingface](https://huggingface.co/spaces/hvoss-techfak/Autoforge) space and pull the docker container for this project (upper right corner -> three dots -> "run locally")
+## 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html), 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:
+   ```bash
+   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:
+```bash
+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:
+   ```bash
+   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):**
+  ```bash
+  docker compose -f docker-compose.cpu.yml up -d --build
+  ```
+  This builds a native arm64 image. In Docker Desktop, raise the memory limit (Settings → Resources) if large images fail with out-of-memory errors.
+
+### CPU only
+
+Works on any machine with Docker, but optimization is much slower than on a GPU:
+```bash
+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:
+```bash
+# 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
+```
+The container runs as root, so on Linux the output files belong to root; `sudo chown -R "$USER" output` makes them yours again.
 
 ## Development
 

{autoforge-2.1.0 → autoforge-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "AutoForge"
-version="2.1.0"
+version="2.2.0"
 description = "AutoForge - 3D color prints made easy"
 authors = [{ name = "Hendric Voss", email = "hvoss@techfak.uni-bielefeld.de" }]
 readme = "README.md"
@@ -51,7 +51,7 @@ test = [
 package-dir = {"" = "src"}
 
 [tool.setuptools.package-data]
-autoforge = ["data/*.json"]
+autoforge = ["data/*.json", "default_materials.csv"]
 
 [project.scripts]
 autoforge = "autoforge.auto_forge:main"

{autoforge-2.1.0 → autoforge-2.2.0}/src/AutoForge.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AutoForge
-Version: 2.1.0
+Version: 2.2.0
 Summary: AutoForge - 3D color prints made easy
 Author-email: Hendric Voss <hvoss@techfak.uni-bielefeld.de>
 License: CC BY-NC-SA 4.0
@@ -93,6 +93,7 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
    - Windows: double-click `run_webui.bat`
 
    This starts the server and opens the web UI in your browser automatically (usually at `http://localhost:8000`).
+   It only listens on this computer by default, since the web UI has no login. To open it from other devices on your network, start it with `WEBUI_HOST=0.0.0.0 ./run_webui.sh` (Windows: `set WEBUI_HOST=0.0.0.0` before `run_webui.bat`). Open it by IP address or by this computer's name; any other name (for example one from a reverse proxy) has to be listed in `AUTOFORGE_WEBUI_ALLOWED_HOSTS` (comma separated).
 
    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.
 
@@ -100,7 +101,7 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
 
    To find a filament you own without measuring it yourself, click **Catalog** in the filament library. It searches every filament on [filamentcolors.xyz](https://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](https://posthog.com/) 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.
+   The web UI sends anonymous usage telemetry to the project via [PostHog](https://posthog.com/) 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 other personal information is sent, except that error messages and stack traces can contain file paths (the backend replaces your home folder in them with `~`, so your user name isn't sent from there; the browser's own stack traces only name the app's script files). 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.
 
 4. **Update to the latest release** whenever you want, from the project folder:
    - Linux/macOS: `./update.sh`
@@ -108,8 +109,17 @@ The easiest way to use AutoForge is the web UI, a local app with drag-and-drop i
 
    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`).
 
-If you have problems running the code on your GPU, please refer to the [Pytorch Homepage](https://pytorch.org/) for help. \
-CUDA, ROCm, and MPS (Apple Metal) are supported, but you need to install the correct version of pytorch for your system — `install.sh`/`install.bat` install whatever `uv sync` resolves by default, so swap in a GPU-specific PyTorch build afterwards if you need one. (`install.sh` handles older NVIDIA GPUs automatically, see below.)
+### 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=<PyTorch wheel index> ./install.sh`, e.g. `https://download.pytorch.org/whl/cpu`. `./update.sh` keeps whichever build was installed.
+
+If the fused GPU kernels (Triton) cause trouble on your GPU, `AUTOFORGE_TRITON=off` switches to the plain PyTorch code path. For other GPU problems, see the [PyTorch homepage](https://pytorch.org/).
 
 ## Manual Installation (CLI only)
 
@@ -184,7 +194,7 @@ This will generate separate STL files for each color, allowing you to print face
 - `--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).  
   **Note:** Details smaller than half this value will be ignored.
-- `--early_stopping` Number of steps without improvement before stopping (default: 10000).
+- `--early_stopping` Number of steps without improvement before stopping (default: 3000).
 - `--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.
 
@@ -234,9 +244,96 @@ After running, the following files will be created in your specified output fold
   
   *Note:* FlatForge generates multiple STL files that align perfectly when loaded together in your slicer, creating a solid rectangular print with each color as a separate object.
 
-## You can now run Autoforge for free in your browser thanks to [Huggingface space support](https://huggingface.co/spaces/hvoss-techfak/Autoforge).
-This includes the option to run it locally if you have a powerful pc and don't want to limit yourself to the Huggingface computing limits. \
-For this simply go to the [Huggingface](https://huggingface.co/spaces/hvoss-techfak/Autoforge) space and pull the docker container for this project (upper right corner -> three dots -> "run locally")
+## 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html), 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:
+   ```bash
+   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:
+```bash
+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:
+   ```bash
+   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):**
+  ```bash
+  docker compose -f docker-compose.cpu.yml up -d --build
+  ```
+  This builds a native arm64 image. In Docker Desktop, raise the memory limit (Settings → Resources) if large images fail with out-of-memory errors.
+
+### CPU only
+
+Works on any machine with Docker, but optimization is much slower than on a GPU:
+```bash
+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:
+```bash
+# 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
+```
+The container runs as root, so on Linux the output files belong to root; `sudo chown -R "$USER" output` makes them yours again.
 
 ## Development
 

{autoforge-2.1.0 → autoforge-2.2.0}/src/AutoForge.egg-info/SOURCES.txt

@@ -9,14 +9,18 @@ src/AutoForge.egg-info/top_level.txt
 src/autoforge/__init__.py
 src/autoforge/__main__.py
 src/autoforge/auto_forge.py
+src/autoforge/default_materials.csv
 src/autoforge/priority_mask_editor.py
 src/autoforge/Helper/AmpUtils.py
 src/autoforge/Helper/CAdamW.py
 src/autoforge/Helper/ConstraintHelper.py
+src/autoforge/Helper/DeterministicOps.py
 src/autoforge/Helper/DeviceUtils.py
 src/autoforge/Helper/FilamentHelper.py
 src/autoforge/Helper/FusedComposite.py
 src/autoforge/Helper/HeightAssign.py
+src/autoforge/Helper/HeightGuidance.py
+src/autoforge/Helper/HeightfieldMesh.py
 src/autoforge/Helper/ImageHelper.py
 src/autoforge/Helper/OptimizerHelper.py
 src/autoforge/Helper/OtherHelper.py
@@ -29,6 +33,7 @@ src/autoforge/Helper/Heightmaps/ChristofidesHeightMap.py
 src/autoforge/Helper/Heightmaps/DepthEstimateHeightMap.py
 src/autoforge/Helper/Heightmaps/FastTSPHeightMap.py
 src/autoforge/Helper/Heightmaps/__init__.py
+src/autoforge/Helper/Heightmaps/_cluster.py
 src/autoforge/Init_comparer/__init__.py
 src/autoforge/Init_comparer/auto_forge_init_check.py
 src/autoforge/Init_comparer/plot_results.py
@@ -46,6 +51,7 @@ src/autoforge/webui/models.py
 src/autoforge/webui/server.py
 src/autoforge/webui/api/__init__.py
 src/autoforge/webui/api/filaments.py
+src/autoforge/webui/api/guidance.py
 src/autoforge/webui/api/images.py
 src/autoforge/webui/api/init.py
 src/autoforge/webui/api/optimization.py
@@ -57,12 +63,18 @@ src/autoforge/webui/api/settings.py
 src/autoforge/webui/api/sliders.py
 src/autoforge/webui/api/state.py
 src/autoforge/webui/api/system.py
+src/autoforge/webui/api/workers.py
 src/autoforge/webui/api/ws.py
 src/autoforge/webui/helpers/__init__.py
+src/autoforge/webui/helpers/auto_prune.py
 src/autoforge/webui/helpers/colored_mesh.py
+src/autoforge/webui/helpers/edited_export.py
 src/autoforge/webui/helpers/gpu_memory.py
+src/autoforge/webui/helpers/guidance_views.py
 src/autoforge/webui/helpers/mesh_persist.py
 src/autoforge/webui/helpers/pipeline_runner.py
+src/autoforge/webui/helpers/project_heightmap.py
+src/autoforge/webui/helpers/result_store.py
 src/autoforge/webui/helpers/slider_render.py
 src/autoforge/webui/helpers/sliders.py
 src/autoforge/webui/helpers/telemetry.py
@@ -76,6 +88,8 @@ tests/test_amp_utils.py
 tests/test_auto_forge_cli.py
 tests/test_bug_regressions.py
 tests/test_bugfixes_2026_09_26.py
+tests/test_bugreport_2026_10_01.py
+tests/test_bugreport_2026_10_03.py
 tests/test_cadamw.py
 tests/test_christofides_heightmap.py
 tests/test_composite_image.py
@@ -83,6 +97,7 @@ tests/test_constrained_opt.py
 tests/test_depth_adjusted_height_map.py
 tests/test_depth_estimate_height_map.py
 tests/test_device_utils.py
+tests/test_edge_bleed.py
 tests/test_end_to_end_optimizer.py
 tests/test_fasttsp_heightmap.py
 tests/test_filament_helper.py
@@ -91,6 +106,7 @@ tests/test_flatforge.py
 tests/test_graph_cache_eviction.py
 tests/test_graph_capture_threads.py
 tests/test_gumbel_nan.py
+tests/test_height_guidance.py
 tests/test_image_helper.py
 tests/test_loss_functions.py
 tests/test_optimizer_module.py
@@ -104,4 +120,5 @@ tests/test_prune_repeatability.py
 tests/test_pruning_helper.py
 tests/test_remove_height_spikes.py
 tests/test_webui_backend.py
-tests/test_webui_regressions.py
+tests/test_webui_regressions.py
+tests/test_worktree_bugs_2026_10_01.py

{autoforge-2.1.0 → autoforge-2.2.0}/src/autoforge/Helper/AmpUtils.py

@@ -30,17 +30,23 @@ def _probe_backward(device: torch.device, dtype: torch.dtype) -> bool:
     here.
     """
     try:
-        x = torch.randn(8, 8, device=device, dtype=torch.float32, requires_grad=False)
-        w = torch.randn(8, 8, device=device, dtype=torch.float32, requires_grad=True)
-        target = torch.randn(8, 8, device=device, dtype=torch.float32)
+        # Fixed inputs, not torch.randn: the probe runs once per process, and
+        # drawing from the device's generator there shifted the random
+        # stream of only the first run - the same seed gave a different
+        # result in the first webui job than in every later one.
+        base = torch.linspace(-1.0, 1.0, 64, device=device, dtype=torch.float32).view(8, 8)
+        x = base.clone()
+        w = base.t().contiguous().requires_grad_(True)
+        target = base.flip(0)
         with torch.autocast(device_type=device.type, dtype=dtype):
             y = x @ w
             loss = torch.nn.functional.mse_loss(y, target)
         loss.backward()
-        # Step with a dummy optimizer to ensure gradients are usable
-        opt = torch.optim.SGD([w], lr=1e-3)
-        opt.step()
-        return True
+        # Apply the gradient to make sure it is usable (a plain update: a
+        # torch.optim optimizer would import torch._dynamo, ~0.7 s).
+        with torch.no_grad():
+            w.add_(w.grad, alpha=-1e-3)
+        return bool(torch.isfinite(w).all())
     except Exception:
         return False
 

{autoforge-2.1.0 → autoforge-2.2.0}/src/autoforge/Helper/CAdamW.py

@@ -61,6 +61,15 @@ class CAdamW(Optimizer):
         super().__init__(params, defaults)
         self.init_lr = lr
 
+    # torch.optim.Optimizer wraps these two in torch._disable_dynamo, whose
+    # first call imports all of torch._dynamo (sympy, fsdp, ...): ~0.7 s per
+    # run for machinery nothing here uses. The undecorated originals.
+    def add_param_group(self, param_group: dict) -> None:
+        return getattr(Optimizer.add_param_group, "__wrapped__", Optimizer.add_param_group)(self, param_group)
+
+    def zero_grad(self, set_to_none: bool = True) -> None:
+        return getattr(Optimizer.zero_grad, "__wrapped__", Optimizer.zero_grad)(self, set_to_none)
+
     @torch.no_grad()
     def step(self, closure: Callable = None):
         """