README.md

---
title: STL to TIFF Slicer
sdk: gradio
sdk_version: 6.10.0
python_version: "3.12"
app_file: app.py
fullWidth: true
short_description: Upload an STL and export a TIFF slice.
---

# STL to TIFF Gradio App

This project provides a Gradio app that takes up to three uploaded STL files, shows interactive 3D viewers, slices each model along the Z axis, saves slices as TIFF images, and lets you browse each stack inside the UI.

## Run

```powershell
uv sync --all-groups
uv run python app.py
```

For reload mode during development, run:

```powershell
uv run gradio app.py
```

When `app.py` changes, Gradio will automatically rerun the file and refresh the demo.

Then open the local Gradio URL in your browser, upload an STL file, and generate the TIFF stack.

## What the app does

- Uploads up to three `.stl` files
- Shows interactive 3D viewers for rotating each model
- Lets you choose layer height and XY pixel size
- Produces one `.tif` image per slice
- Encodes material as black (`0`) and empty space as white (`255`) in each TIFF slice
- Lets you step through the slice stack in the browser
- Exports a ZIP containing the generated TIFF images

## Behavior and Implementation Notes

### Reference TIFF Stack Alignment

When you click **Generate Reference TIFF Stack**, the app combines available TIFF stacks layer-by-layer.

- If source TIFFs have different dimensions, each layer is placed on a canvas using the largest width and height.
- Layers are centered in X and Y before merging.
- Pixel merge uses a black-wins rule: a pixel is black in the reference if any source has black at that pixel.
- Alignment is centered image placement, not bottom-left anchoring.
- If image-size differences are odd, centering may produce a one-pixel shift due to integer rounding.

### G-code XY Step Size

- G-code generation uses the slicer's `Pixel Size/Fill Width` for XY step distance by passing `fil_width=pixel_size` into `generate_snake_path_gcode()`.

## Test

```powershell
uv run pytest
```

## Hugging Face Deployment

This repository tracks `.stl` files with Git LFS (see `.gitattributes`).

Before your first push on a machine:

```powershell
git lfs install
git lfs pull
```

Recommended push flow:

```powershell
git push origin main
git push hf-space main
```

If Hugging Face rejects a push for binary files, verify LFS setup first:

```powershell
git lfs version
git lfs ls-files
```

Warning: `git lfs migrate` rewrites commit history. Use it only when you intentionally want history rewritten and all collaborators are aligned.