The Problem

Replicating a physical key typically requires either the original blank or a visit to a locksmith. KeyForge3D removes that dependency: a photo of a key becomes a 3D-printable STL file. For locksmiths, that means a customer can email a photo and get a working copy without a physical visit. For hobbyists, it turns an everyday object into a printable part.

What This Does

KeyForge3D is a single-file Tkinter application, keyforge3d.py, that extracts a key's 2D profile from an image, detects its bitting pattern (the cut depths along the blade), extrudes the profile into a 3D mesh, and exports it as key_model.stl. The GUI has two actions: upload_image to load a photo and process_key to run the pipeline.

The repo is minimal: one Python file, a README (English and Turkish), a license, and two sample images. The README documents dependencies (opencv-python, numpy, trimesh, shapely, pillow) and states the current scale assumption of 1 pixel = 0.1 mm, with reference-object scaling on the roadmap.

How It Is Wired

Execution starts at keyforge3d.py. The KeyForge3DApp class constructs the Tkinter window; the upload_image handler reads the selected file and displays it; process_key runs the image-processing and mesh-generation pipeline and writes key_model.stl to disk. The call graph is flat: three functions, one class, one internal module, no cycles. Nothing routes through a shared hub, so changing one function does not ripple elsewhere.

The entire pipeline—image load, processing, mesh build, file write—lives in keyforge3d.py. All external effects (OpenCV, NumPy, Trimesh, file I/O) leave from that file. The internal graph resolves only one code module, so the wiring between image processing and mesh generation is not separately mapped; the README's code overview is the only description of that flow.

How To Use It

git clone https://github.com/moses-y/KeyForge3D.git
cd KeyForge3D
pip install opencv-python numpy trimesh shapely pillow
python keyforge3d.py

No configuration files or environment variables exist. The GUI accepts a key photo via the "Upload Key Image" button, then "Process Key and Generate 3D Model" writes key_model.stl to the working directory. The README recommends a plain background and good lighting for reliable extraction.

Real-World Use

A locksmith receives a photo of a customer's key. After running the app and generating the STL, they slice it in Cura or PrusaSlicer and print in PLA or ABS at 0.1 mm layer height. The printed key works for low-security locks, which tolerate minor dimensional error; the current 0.1 mm/pixel scale assumption means accuracy degrades with photo distance, so the README's planned reference-object scaling is the practical fix for consistent results.

Code Health & Issues

Static analysis found one medium issue, one distinct kind:

  • Medium (resource safety) — open(...) in keyforge3d.py is not wrapped in a with block; the file handle may leak on error. Use with open(...) as f: for deterministic close.

SDLC observations from the file structure:

  • Medium — no tests — no test files exist; the image-processing pipeline is untested.
  • Medium — no CI/CD — no .github/ or CI config; no automated gate on changes.
  • Low — single-file architecture — all logic in one module; the README's roadmap items (preview, key-type detection) will require splitting this out.

The license file is present; no secrets or lockfiles were found.

The Bottom Line

A functional proof of concept that does exactly what it claims: photo in, STL out, in one file and a few clicks. It is not production-grade—no tests, no CI, a fixed scale assumption, and one resource leak—but for a locksmith or hobbyist wanting a quick printable copy, it is a usable starting point. Treat it as a prototype to harden before relying on it for real key replication.