# Tracefinity: turning a photo of your tools into 3D printable gridfinity bins

> Tracefinity is a Python and Next.js application that photographs tools on a sheet of paper, traces their outlines with a segmentation model, and exports gridfinity bins as STL or 3MF for printing, with a local ONNX tracer that needs no API key. It suits a maker with a drawer to organise, and it depends on a segmentation model producing clean outlines of objects that are not flat.

**tracefinity/tracefinity** — Generate custom gridfinity bins with AI, from photos of your tools

- Repository: https://github.com/tracefinity/tracefinity
- Stars: 707 · Forks: 105
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/tracefinity-tracefinity

## Eight steps from a photo on a desk to an STL on the printer

The workflow is described as a numbered list, and the order tells you what the application actually does.

You place tools on A4, Letter, A3 or Tabloid paper, with the note that tools can overflow the edges. You take a photo from above. You upload it and adjust the paper corners for scale calibration. The AI traces the tool outlines automatically. You save traced tools to your library. You group tools into projects when planning a drawer or workspace. You create bins from the project tools and arrange the layout. And you download STL or 3MF for 3D printing.

The interesting design decision is in step three, the paper corner adjustment. A photo has no absolute scale, so the application asks the user to mark the corners of a sheet whose size is known, which is how the image gets calibrated to millimetres. That is a manual step and a manual step in a flow otherwise billed as automatic, and it is also the step that determines whether the output dimensions are right. The paper is not decoration, it is the ruler.

The library, projects and bins are three separate concepts. A tool is a traced outline, saved and reusable. A project is a group of tools, which is the unit you plan a drawer around. A bin is generated from a set of project tools with a layout arranged in the bin editor. The three screens in the screenshots, dashboard, tool editor and bin editor, map onto that structure exactly.

## The local tracer is the default, and it is why no API key is needed

By default, Tracefinity uses IS-Net for local tracing, and the documentation says plainly that no API key is needed. Set GOOGLE_API_KEY to use Gemini instead.

The IS-Net reference is to a specific saliency and segmentation model, and the local tracing path runs on ONNX through a local provider controlled by TRACEFINITY_ONNX_PROVIDER, which can be auto, cuda or cpu, with auto preferring CUDA when it is available. The TRACERS variable takes a comma-separated list of available tracers, for example gemini,birefnet-lite,isnet, and when it is set it is the complete list; unset with a Gemini or OpenRouter key, it offers gemini only.

The local models are not free in machine terms. The documentation says the local tracing models load at startup and require at least 2GB of memory, and the Docker section says ARM devices need at least 2GB RAM for U2-Net paper detection, so a Raspberry Pi 4 or 5 with 4GB works. The Helm section repeats the same constraint, telling you to set resource limits accordingly.

So the choice is between a machine that can hold a segmentation model in memory and a photo leaving your network. The remote path supports Gemini through GOOGLE_API_KEY, and remote saliency through fal.ai with FAL_KEY or Replicate with REPLICATE_API_TOKEN, and the remote path is described as remote saliency rather than a full cloud service, which is a narrower description than Gemini's image generation implies.

## The privacy detail that a paper crop makes unavoidable

The documentation is unusually candid about what happens to a photo when a remote provider is used, and it deserves to be read rather than skimmed.

With a remote provider, the corrected paper crop is sent to that provider for masking. When a tool overhangs the sheet, the crop grows past the paper edge and is sent again, so some of the surrounding photo can go to the provider in a second or third request.

That second sentence is the interesting one. The crop is supposed to be the paper, and the point of the calibration is to remove everything outside it. But an overhanging tool means the paper rectangle no longer contains the tool, so the crop is expanded to include it, and an expanded rectangle in a photo of a workbench includes workbench. The user is told this in plain terms rather than being left to discover it.

The retention story is also spelled out per provider. fal is called with sync_mode, so the result is not kept in request history. Replicate API predictions, including the input image, auto-purge after about an hour, which the documentation calls the only retention control Replicate exposes, since it has no API to delete them sooner.

That is a fair trade to understand before you point a remote tracer at a photo taken on a desk in a room you work in.

## Configuration is a table of environment variables, and two of them are security relevant

The configuration surface is a table of environment variables with defaults, and most of them are about running the service rather than about the tracing itself.

MAX_UPLOAD_MB defaults to 20 for the maximum compressed upload size, and MAX_IMAGE_PIXELS defaults to 64000000 for the maximum decoded pixels accepted before downscaling. Those two are the input limits, and they are the settings you would raise if you wanted to photograph a large sheet at high resolution.

STL_GENERATION_CONCURRENCY defaults to unlimited as a process-wide maximum for STL generation jobs, with excess jobs waiting up to 5 seconds and then receiving a 503. STL_RETENTION_HOURS defaults to 24, so generated STL, 3MF and zip exports are deleted by a background sweep after a day, and a bin page regenerates them on the next visit or export download; setting it to 0 keeps exports forever. That is a sensible default for a service that produces files on demand rather than storing them.

The security-relevant ones are in the authentication group. AUTH_MODE defaults to native, meaning a cookie login, with proxy for a trusted reverse proxy, which is deprecated, and open for no authentication on trusted networks only. AUTH_SECRET encrypts the 2FA secrets at rest and is auto-generated into the storage volume when unset. AUTH_COOKIE_SECURE defaults to false and marks the cookie Secure when set to true, which you want behind TLS. AUTH_COOKIE_DOMAIN is host-only by default and exists for subdomain topologies, and PROXY_SECRET is a shared secret for the trusted multi-user reverse proxy mode.

The defaults are the interesting part. AUTH_COOKIE_SECURE false and AUTH_MODE native with cookie login means a default deployment on a plain HTTP port is a deployment where the session cookie is not marked Secure. The first visit prompts you to create an administrator account, and any data from an earlier version is claimed by that account, untouched on disk.

## One container, three run modes, and a Helm chart for the same thing

The deployment story is the shortest part of the documentation and the most useful, because it covers the three ways people actually run this.

The plain Docker run with no key at all uses the local model:

```bash
# local model (no API key needed)
docker run -p 3000:3000 -v ./data:/app/storage ghcr.io/tracefinity/tracefinity
```

The same command with a key switches the tracer, either Gemini through GOOGLE_API_KEY, or remote saliency through fal.ai with FAL_KEY, or through Replicate with REPLICATE_API_TOKEN. And there is a variant that runs the container as your host user, with --user "$(id -u):$(id -g)", so the files written into the mounted data directory belong to you rather than to root.

The image supports linux/amd64 and linux/arm64, so Apple Silicon machines run arm64 natively through Docker Desktop. The compose file in the repository is the same shape as the documented one, and the chart is a Helm chart in the oci://ghcr.io/tracefinity/charts/tracefinity registry, installed with a namespace, a persistence block and a size:

```bash
helm install tracefinity oci://ghcr.io/tracefinity/charts/tracefinity \
  --namespace tracefinity \
  --create-namespace \
  --set persistence.enabled=true \
  --set persistence.size=5Gi
```

Adding Gemini to the Helm install is a matter of setting env.GOOGLE_API_KEY, and an alternative is a values.yaml with a persistence block and an env block.

Underneath, the Dockerfile is a two-stage build that is worth reading if you care about the image size. The front end is built in a node:20-slim stage with pnpm and a frozen lockfile, and the runtime is python:3.12-slim with nginx and supervisor installed alongside the system libraries needed for image decoding, including libheif-dev. The Python side installs torch and torchvision from the CPU-only PyTorch index, which is the difference between a usable image and a multi-gigabyte one.

## Where Tracefinity is the wrong tool

The first limit is the geometry. The output is derived from a segmentation mask of a top-down photograph, so the traced outline is a visual estimate of an object's silhouette, not a measurement of it. A tool with a handle seen at an angle, a tool that is not flat, or a tool photographed with a shadow will produce an outline that is close but not exact, and a bin designed from that outline will fit approximately. If you need a bin that a specific tool fits to the millimetre, you are going to edit the STL anyway.

The second limit is the 2GB memory floor and what it implies. The local models load at startup and need at least 2GB, and the tracing is not the only consumer of memory, since the app also holds the image, the mask and the mesh generation. The Raspberry Pi case is called out as workable with 4GB, which tells you the intended low end, and the model list in TRACERS lets you trade quality for footprint by removing birefnet or isnet from the list.

The third is the calibration step. The paper corners are adjusted by the user, and that is where dimensional accuracy comes from. A user who marks the corners carelessly gets a bin that is the right shape and the wrong size, and the failure is silent because the output still looks plausible.

The fourth is that a remote tracer sends a photo of your workbench, and while the documentation is honest about it, that photo may contain more than the tool. The overhang case is described, but a cluttered bench is a general case, not just an overhang case.

The fifth is the scope of the output. The documentation describes the flow as generating bins and downloading STL or 3MF, and the tree has a backend/ and frontend/ split with a Makefile, a Dockerfile, a chart/ directory for the Helm chart, and a docs/ directory. There is no mention of tolerance settings, of how the meshes are validated, or of a way to make a fit exact by hand inside the application. For a one-off hobby bin, none of that matters. For a bin that has to hold a specific tool, it does.

## Conclusion

Tracefinity is worth installing for someone with a drawer of loose tools who wants custom gridfinity bins without modelling each one, because the whole pipeline from a top-down photo to a printable file is automated, and because the local IS-Net tracer means the tracing step works with no API key and no photo leaving the machine. It is the wrong tool if your tools are not flat, if you need the output to be dimensionally exact rather than a close visual match, or if you want production-grade output without checking each result. Before you rely on it, check the three things the documentation states: the memory floor of 2GB for the local paper detection model, which sets what hardware the app can run on, including a Raspberry Pi 4 or 5 with 4GB; the upload and pixel limits, with MAX_UPLOAD_MB at 20 and MAX_IMAGE_PIXELS at 64000000 before downscaling; and where your photos actually go, because with a remote provider the corrected paper crop is sent to that provider for masking, and when a tool overhangs the sheet the crop grows past the paper edge and the surrounding photo can go out in a second or third request.

## FAQ

### How do I run Tracefinity without an AI API key?

Run the container without any key environment variable, for example docker run -p 3000:3000 -v ./data:/app/storage ghcr.io/tracefinity/tracefinity. By default it uses IS-Net for local tracing and needs no API key, but the local models load at startup and require at least 2GB of memory, so set resource limits accordingly.

### What happens to my photo when I use a remote tracer in Tracefinity?

The corrected paper crop is sent to the provider for masking, and when a tool overhangs the sheet the crop grows past the paper edge and is sent again, so some of the surrounding photo can go to the provider in a second or third request. fal is called with sync_mode so the result is not kept in request history, and Replicate predictions including the input image auto-purge after about an hour.

### How do I install Tracefinity on Kubernetes?

Log in to the ghcr.io registry with helm registry login, then install the OCI chart with helm install tracefinity oci://ghcr.io/tracefinity/charts/tracefinity, setting persistence.enabled=true and a persistence size, and adding env.GOOGLE_API_KEY if you want Gemini instead of the local model.

## Sources

- [Issues](https://github.com/tracefinity/tracefinity/issues)
- [License: MIT](https://github.com/tracefinity/tracefinity/blob/main/LICENSE)
- [README](https://github.com/tracefinity/tracefinity/blob/main/README.md)
- [Releases](https://github.com/tracefinity/tracefinity/releases)
- [tracefinity/tracefinity on GitHub](https://github.com/tracefinity/tracefinity)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tracefinity-tracefinity