Passthrough Fidget Generator

Generate interlocking passthrough fidgets from existing 3D models.

The generator takes an existing STL, OBJ, or PLY model and splits it into two interlocking pieces using a smooth curved interface. The resulting pieces can be printed separately and assembled into a passthrough fidget.

Features

• Generate passthrough fidgets from existing 3D models
• Smooth mathematical curved interfaces
• Configurable clearance
• Configurable waves
• Configurable twists
• Configurable radius scale
• Configurable radial resolution
• Configurable height resolution
• STL output
• Command-line interface
• Python API

Installation

Install from PyPI:

pip install passthrough-fidget-generator

Command Line

Basic usage:

passthrough-fidget-generator model.stl

Specify an output directory:

passthrough-fidget-generator model.stl -o output

Parameters

--clearance

Sets the gap between the two pieces.

--clearance 0.3

The value uses the same units as the input model.

--waves

Controls the number of waves along the height of the model.

--waves 1.5

--twists

Controls how many rotations the interface makes around the model.

--twists 2

--radius

Sets the base radius of the spiral cutout.

--radius 2.0

The value uses the same units as the input model. If set to 0 (default), the radius is calculated automatically.

--radius-scale

Controls the fraction of the model's smaller XY extent used for the spiral cutout radius when --radius is 0.

--radius-scale 0.4

Larger values produce a wider cutout. The default is 0.35.

--radial-samples

Controls the resolution around the curved interface.

--radial-samples 128

Higher values produce smoother surfaces but require more processing.

--height-samples

Controls the resolution along the height of the interface.

--height-samples 64

Higher values produce smoother surfaces but require more processing.

Example

passthrough-fidget-generator model.stl \
    --clearance 0.3 \
    --waves 1.5 \
    --twists 2 \
    --radius-scale 0.4 \
    --radial-samples 128 \
    --height-samples 64 \
    -o output

Python API

The generator can be used directly from Python:

from passthrough_fidget_generator import generate_from_file

paths = generate_from_file(
    "model.stl",
    output="output",
    clearance=0.3,
    waves=1.5,
    twists=2,
    radial_samples=128,
    height_samples=64,
)

You can also work directly with a trimesh.Trimesh object:

from passthrough_fidget_generator import generate

inner, outer = generate(
    mesh,
    clearance=0.3,
    waves=1.5,
    twists=2,
    amplitude=0.0,
    radius=0.0,
    radius_scale=0.35,
    radial_samples=128,
    height_samples=64,
)

Input Models

The input should be a closed, watertight solid.

Supported formats depend on the underlying trimesh installation, including:

• STL
• OBJ
• PLY

Non-watertight or invalid meshes may fail during the boolean operations used to create the pieces.

How It Works

The generator:

1. Loads the input mesh.
2. Creates a smooth mathematical interface through the model.
3. Uses boolean operations to divide the original model along that interface.
4. Applies the requested clearance.
5. Extracts the resulting inner and outer pieces.
6. Writes the generated meshes as STL files.

The interface is generated mathematically rather than using voxelization, allowing the resulting pieces to have smooth curved surfaces.

Dependencies

The project uses:

• NumPy
• SciPy
• Trimesh
• Manifold3D
• scikit-image
• NetworkX

These dependencies are installed automatically when installing from PyPI.

Development

Clone the repository:

git clone https://github.com/gooficat/passthrough_fidget_generator.git
cd passthrough_fidget_generator

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install the package in editable mode:

pip install -e .

Run the tests:

pytest

Building

Build the package with:

python -m build

The distribution files will be created in:

dist/