FiftyOne 3DP Model Management

Your 3D-printing model library, visually browsable. Drop your downloads into a folder; fo-3dp shows you the whole collection as an interactive grid of 3D thumbnails you can filter, sort, and search by what they are and how they print; powered by FiftyOne.

Under the hood it loads your STL and 3MF files into FiftyOne: a visual dataset tool from the computer-vision world, and pulls metadata out of the Printables PDFs that ship with each download.

fo3d-overview.mov

What it gives you

• A real visual library. Every model rendered as an isometric thumbnail in one scrollable grid, with a full 3D viewer when you click a sample.
• STL and 3MF in the same view. Both formats land in one dataset.
• Automatic metadata. Titles, authors, tags, print specs, license pulled from the Printables PDFs you already have. Missing fields are simply blank; the grid handles it gracefully.
• Fast filters and sorting. Material, category, print time, layer height, author, license, dates; all indexed in FiftyOne.
• A workshop schema for your own data. Track which models you've printed, rate them, mark what's next in the queue, note which filament worked. Stored alongside your files so it survives moves and backups.
• Optional similarity search. Find visual lookalikes and duplicates using image embeddings, works with any FiftyOne zoo embedding model.
• Cross-platform. Linux, macOS, Windows. (Needs a real display — no headless servers.)

Install

fo-3dp ships as a Python package you install with uv. uv bundles Python, virtual environments, and a git fetcher, so you don't need separate installs of Python or git.

1. Install uv once (skip if you already have it):

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Create a working folder, set up a venv, install fo-3dp:

mkdir fo-3dp-workspace && cd fo-3dp-workspace
uv venv
uv pip install "git+https://github.com/Burhan-Q/fo-3dp"

3. Activate the venv and point fo-3dp at your models:

# macOS / Linux
source .venv/bin/activate
fo-3dp --path /path/to/my-3dp-models

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
fo-3dp --path "C:\path\to\my-3dp-models"

The FiftyOne App opens at http://localhost:5151.

Prefer the source? Clone the repo or download the ZIP from GitHub and use uv sync instead of uv pip install. That path also unlocks the curated PyTorch backend matrix used by similarity search (see below). Details: QUICKSTART.

New to running commands in a terminal? QUICKSTART walks through it step by step, including how to find Terminal/PowerShell on each OS.

Coming soon (pending demand): a FiftyOne App plugin so you can import new models, edit metadata, jump to files in Finder/Explorer, purge the cache, and search across fields without leaving the App. Open an issue if you want it, considering opening a GitHub issue (or 👍 existing issue); demand drives priority. See ROADMAP for the full plan.

Where to look next

• QUICKSTART.md: step-by-step setup for people who haven't used Python or uv before.
• docs/TECHNICAL.md: CLI reference, the full sample-fields schema, the sidecar format, how caching works.
• ROADMAP.md: what's planned next, including the FiftyOne plugin.

What gets created on your machine

Three things appear the first time you run fo-3dp:

• ~/.fo3dp/config.toml (Windows: %USERPROFILE%\.fo3dp\config.toml) — your configuration: model directory, dataset name, embedding model, optional cache override. Edit it any time.
• ~/.cache/fo3dp/ (Windows: %USERPROFILE%\.cache\fo3dp\) — generated 3D scenes and thumbnails so subsequent runs finish in seconds. Safe to delete; will be regenerated. Try fo-3dp --purge-cache to clear it cleanly. You can override the location with the optional cache_dir config key.
• .fo3dp.yaml inside each collection (subdirectory of your models folder) — a small YAML file holding your workflow data (which models you've printed, ratings, queue, etc.). These travel with your files: if you back up or move a collection, your workflow data goes with it.

You don't need to know the schema to use the tool. If you want to hand-edit your workflow fields or understand the cache, see docs/TECHNICAL.md.

Optional: similarity search

fo3d-embedding.mov

CLIP-style image embeddings let you find visually-similar models, score uniqueness, and lay out your library as a 2-D map you can pan and click around. You need PyTorch for this feature, pick the backend group that matches your hardware:

uv sync --group embeddings --group cpu          # CPU only (works everywhere but slower)
uv sync --group embeddings --group cuda12-8     # NVIDIA GPU, CUDA 12.8
uv sync --group embeddings --group cuda13-0     # NVIDIA GPU, CUDA 13.0
uv sync --group embeddings --group rocm         # AMD GPU
uv sync --group embeddings --group xpu          # Intel GPU

Then:

uv run python run.py --embeddings

That gives you a similarity index, per-sample uniqueness scores, and a 2-D visualization of the embedding space in the App's Embeddings panel.

Any image-embedding model from the FiftyOne Model Zoo works: not just CLIP. The default is clip-vit-base32-torch (small and fast). Examples of alternatives:

Model id	Notes
clip-vit-base32-torch	Default; small CLIP, fast
clip-vit-large-patch14-torch	Larger CLIP, richer embeddings, slower
dinov2-vitl14-torch	DINOv2: strong self-supervised visual features
open-clip-torch	OpenCLIP: community CLIP variants

Pick a different one with --embedding-model NAME (or set embedding_model in your config). See docs/TECHNICAL.md for the full how-to.

Multiple model directories

If your models live in more than one place, say one on your main drive and one on an external, fo-3dp can index them all at once. Edit your ~/.fo3dp/config.toml (Windows: %USERPROFILE%\.fo3dp\config.toml) and turn models_dir into a list:

# Single root folder (the default)
models_dir = "/path/to/my-3dp-models"

# Or multiple root folders (macOS/Linux example)
models_dir = [
    "/path/to/my-3dp-models",
    "/Volumes/External/printables",
]

# Windows example — note the escaped backslashes
# models_dir = [
#     "C:\\Users\\you\\3dprints",
#     "D:\\printables",
# ]

When multiple root folders are configured, collection ids are prefixed with the root's basename, so /main/dragon and /external/dragon are kept distinct as my-3dp-models/dragon and printables/dragon. If two root folders themselves share a basename, fo-3dp exits with a clear error asking you to rename one.

License

Apache License 2.0: see LICENSE.