autoforge 2.1.1__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AutoForge
-Version: 2.1.1
+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`
@@ -193,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.
 
@@ -334,10 +335,6 @@ docker run --rm -v "$PWD:/work" -w /work autoforge-webui:cpu \
 ```
 The container runs as root, so on Linux the output files belong to root; `sudo chown -R "$USER" output` makes them yours again.
 
-## 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")
-
 ## Development
 
 To have a "nightly" version of the repository or have live updating changes during development please do the following: 

{autoforge-2.1.1 → 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`
@@ -156,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.
 
@@ -297,10 +298,6 @@ docker run --rm -v "$PWD:/work" -w /work autoforge-webui:cpu \
 ```
 The container runs as root, so on Linux the output files belong to root; `sudo chown -R "$USER" output` makes them yours again.
 
-## 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")
-
 ## Development
 
 To have a "nightly" version of the repository or have live updating changes during development please do the following: 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "AutoForge"
-version="2.1.1"
+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.1 → autoforge-2.2.0}/src/AutoForge.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AutoForge
-Version: 2.1.1
+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`
@@ -193,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.
 
@@ -334,10 +335,6 @@ docker run --rm -v "$PWD:/work" -w /work autoforge-webui:cpu \
 ```
 The container runs as root, so on Linux the output files belong to root; `sudo chown -R "$USER" output` makes them yours again.
 
-## 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")
-
 ## Development
 
 To have a "nightly" version of the repository or have live updating changes during development please do the following: 

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

@@ -9,6 +9,7 @@ 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
@@ -18,6 +19,7 @@ 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
@@ -49,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
@@ -60,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
@@ -79,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
@@ -95,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
@@ -108,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.1 → autoforge-2.2.0}/src/autoforge/Helper/AmpUtils.py

@@ -30,9 +30,14 @@ 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)

{autoforge-2.1.1 → autoforge-2.2.0}/src/autoforge/Helper/DeterministicOps.py

@@ -40,6 +40,11 @@ def gather_plan(labels: torch.Tensor, n: int):
 
 def segment_gather(values: torch.Tensor, labels: torch.Tensor, plan) -> torch.Tensor:
     """``values[labels]`` with a deterministic backward (see gather_plan)."""
+    from autoforge.Helper import DeviceUtils
+
+    if not DeviceUtils.has_float64(values.device):
+        # Its backward sums in float64, which MPS doesn't have.
+        return values[labels]
     return _SegmentGather.apply(values, labels, *plan)
 
 

{autoforge-2.1.1 → autoforge-2.2.0}/src/autoforge/Helper/DeviceUtils.py

@@ -74,6 +74,12 @@ def backend_of(device: torch.device) -> str:
     return device.type
 
 
+def has_float64(device: torch.device) -> bool:
+    """False on MPS, which has no float64: creating or casting to a float64
+    tensor there raises, so float64 work has to stay on the host."""
+    return device.type != "mps"
+
+
 def is_accelerator(device: torch.device) -> bool:
     return device.type in ("cuda", "mps")
 
@@ -133,6 +139,19 @@ def resolve_device(spec: Optional[str] = None, args=None) -> torch.device:
     return torch.device("cpu")
 
 
+def activate_device(device: Optional[torch.device]) -> None:
+    """Make ``device`` the current CUDA device of the calling thread.
+
+    Triton kernels and CUDA graph capture run on the *current* device, not
+    on the device of their tensors, so ``--device cuda:1`` without this
+    launched the fused kernels on GPU 0 with pointers into GPU 1. The
+    current device is per thread: every thread that runs GPU work for a
+    run (the webui's job, pruning and render threads) has to call this."""
+    # A bare "cuda" means the current device already; set_device needs an index.
+    if device is not None and device.type == "cuda" and device.index is not None and cuda_is_available():
+        torch.cuda.set_device(device)
+
+
 def _device_is_usable(device: torch.device) -> bool:
     if device.type == "cuda":
         if not cuda_is_available():

{autoforge-2.1.1 → autoforge-2.2.0}/src/autoforge/Helper/FilamentHelper.py

@@ -23,12 +23,14 @@ def load_materials(args):
             - colors_list (list): List of color hex strings.
     """
     df = load_materials_pandas(args)
+    _check_material_table(df)
+    # An empty CSV cell is NaN in pandas; str() turned it into "nan".
     material_names = [
-        str(brand) + " - " + str(name)
+        " - ".join(part for part in (_text(brand), _text(name)) if part)
         for brand, name in zip(df["Brand"].tolist(), df["Name"].tolist())
     ]
     material_TDs = (df["Transmissivity"].astype(float)).to_numpy()
-    colors_list = df["Color"].tolist()
+    colors_list = [normalize_hex(color) for color in df["Color"].tolist()]
     # Use float64 for material colors.
     material_colors = np.array(
         [hex_to_rgb(color) for color in colors_list], dtype=np.float64
@@ -36,6 +38,34 @@ def load_materials(args):
     material_TDs = np.array(material_TDs, dtype=np.float64)
     return material_colors, material_TDs, material_names, colors_list
 
+def _check_material_table(df) -> None:
+    """Exit with a message naming the problem instead of failing later: a
+    missing TD became NaN and turned the whole loss into NaN, and an empty
+    or malformed colour only failed once the run had started."""
+    problems = []
+    for column in ("Brand", "Name", "Color", "Transmissivity"):
+        if column not in df.columns:
+            problems.append(f"missing column '{column}'")
+    if not problems:
+        for row, (color, td) in enumerate(zip(df["Color"].tolist(), df["Transmissivity"].tolist()), start=1):
+            label = f"material {row} ({_text(df['Brand'].iloc[row - 1])} {_text(df['Name'].iloc[row - 1])})".strip()
+            try:
+                normalize_hex(color)
+            except ValueError:
+                problems.append(f"{label}: color {color!r} is not a hex color like #RRGGBB")
+            try:
+                td_value = float(td)
+            except (TypeError, ValueError):
+                td_value = float("nan")
+            if not np.isfinite(td_value) or td_value <= 0:
+                problems.append(f"{label}: transmissivity (TD) {td!r} must be a positive number")
+    if len(df) == 0:
+        problems.append("no materials")
+    if problems:
+        print("Error: invalid material file:\n  " + "\n  ".join(problems), file=sys.stderr)
+        sys.exit(1)
+
+
 def load_materials_pandas(args):
     csv_filename = args.csv_file
     json_filename = args.json_file
@@ -47,16 +77,15 @@ def load_materials_pandas(args):
             traceback.print_exc()
             print("Error reading filament CSV file:", e)
             sys.exit(1)
-        # rename all columns that start with a whitespace
-        df.columns = [col.strip() for col in df.columns]
-        # if TD in columns rename to Transmissivity
-        if "TD" in df.columns:
-            df.rename(columns={"TD": "Transmissivity"}, inplace=True)
     else:
         # read json
-        with open(json_filename, "r") as f:
+        with open(json_filename, "r", encoding="utf-8-sig") as f:
             data = json.load(f)
-        if "Filaments" in data.keys():
+        if isinstance(data, list):
+            # A bare list of filaments (our own export) works as well as
+            # HueForge's {"Filaments": [...]}.
+            pass
+        elif isinstance(data, dict) and "Filaments" in data:
             data = data["Filaments"]
         else:
             print(
@@ -65,6 +94,11 @@ def load_materials_pandas(args):
             sys.exit(1)
         # list to dataframe
         df = pd.DataFrame(data)
+    # Same column spellings for both sources: a JSON library using "TD" (or
+    # padded keys) used to fail with KeyError 'Transmissivity'.
+    df.columns = [str(col).strip() for col in df.columns]
+    if "TD" in df.columns and "Transmissivity" not in df.columns:
+        df.rename(columns={"TD": "Transmissivity"}, inplace=True)
     return df
 
 def load_materials_data(args):
@@ -84,17 +118,38 @@ def load_materials_data(args):
     return records
 
 
+def _text(value) -> str:
+    """A table cell as text; missing / NaN cells are empty."""
+    if value is None or (isinstance(value, float) and np.isnan(value)):
+        return ""
+    return str(value).strip()
+
+
+def normalize_hex(hex_str) -> str:
+    """``#RRGGBB`` for the hex spellings libraries use (``RRGGBB``, ``#RGB``,
+    ``#RRGGBBAA``); ValueError for anything else."""
+    text = str(hex_str).strip().lstrip("#")
+    if len(text) == 3:
+        text = "".join(c * 2 for c in text)
+    elif len(text) == 8:
+        text = text[:6]
+    if len(text) != 6 or any(c not in "0123456789abcdefABCDEF" for c in text):
+        raise ValueError(f"{hex_str!r} is not a hex color like #RRGGBB")
+    return "#" + text.upper()
+
+
 def hex_to_rgb(hex_str):
     """
     Convert a hex color string to a normalized RGB list.
 
     Args:
-        hex_str (str): The hex color string (e.g., '#RRGGBB').
+        hex_str (str): The hex color string ('#RRGGBB'; '#RGB', '#RRGGBBAA'
+            and a missing '#' are accepted too).
 
     Returns:
         list: A list of three floats representing the RGB values normalized to [0, 1].
     """
-    hex_str = hex_str.lstrip("#")
+    hex_str = normalize_hex(hex_str).lstrip("#")
     return [int(hex_str[i : i + 2], 16) / 255.0 for i in (0, 2, 4)]
 
 
@@ -113,11 +168,11 @@ def extract_colors_from_swatches(swatch_data):
 
     # convert to the same format as the hueforge csv files
     material_names = [str(brand) + " - " + str(name) for (brand, name) in out.keys()]
-    material_colors = np.array(
-        [hex_to_rgb("#" + color) for color, _ in out.values()], dtype=np.float64
-    )
+    # normalize_hex: the swatch's hex may or may not carry the "#" ("#" +
+    # "#ff0000" failed), and colors_list is "#RRGGBB" like load_materials'.
+    colors_list = [normalize_hex(color) for color, _ in out.values()]
+    material_colors = np.array([hex_to_rgb(color) for color in colors_list], dtype=np.float64)
     material_TDs = np.array([td for _, td in out.values()], dtype=np.float64)
-    colors_list = [color for color, _ in out.values()]
 
     return material_colors, material_TDs, material_names, colors_list
 
@@ -140,7 +195,7 @@ def swatch_data_to_table(swatch_data):
                 "Brand": brand,
                 "Name": name,
                 "TD": td,
-                "HexColor": f"#{hex_color}",
+                "HexColor": "#" + str(hex_color).lstrip("#"),
                 "Uuid": str(uuid.uuid4()),
             }
         )