Passthrough Fidget Generator

A Python generator for creating interlocking passthrough fidgets from existing 3D models.

The generator takes a watertight STL/OBJ/PLY model and creates two separate meshes:

• inner.stl — the inner/interlocking piece
• outer.stl — the surrounding piece
• combined.stl — both pieces together for inspection

The interlocking boundary is generated from a mathematical curved surface rather than voxelizing the model.

Requirements

• Python 3.10+
• NumPy
• Trimesh
• Manifold3D

Install the dependencies with:

pip install numpy trimesh manifold3d

Usage

Basic example:

python main.py model.stl

This creates:

output/
├── inner.stl
├── outer.stl
└── combined.stl

Example

python main.py "xyz-10mm-calibration-cube (1).stl" \
    --clearance 0.3 \
    --waves 1.5 \
    --twists 2 \
    --radial-samples 128 \
    --height-samples 64 \
    -o output

Options

--clearance

Controls the gap between the two pieces.

--clearance 0.3

The value uses the same units as the input model. For an STL in millimetres, this is 0.3 mm.

Typical starting values:

0.2 mm  Tight
0.3 mm  Normal
0.4 mm  Loose
0.5 mm  Very loose

The correct value depends on the printer and material.

--waves

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

--waves 1.5

Higher values produce more interlocking sections.

--twists

Controls how much the wave rotates around the object.

--twists 2

Higher values create more twisting between the inner and outer pieces.

--amplitude

Controls how far the curved interface moves from its base radius.

--amplitude 1.0

If omitted or set to 0, the generator chooses an amplitude automatically.

--radius

Controls the base radius of the curved interface.

--radius 2.5

If set to 0, the radius is calculated automatically from the input model.

--radial-samples

Controls the number of points around the curved surface.

--radial-samples 256

Higher values produce a smoother circular direction but increase processing time and STL size.

--height-samples

Controls the number of points along the height of the curved surface.

--height-samples 128

Higher values produce a smoother vertical curve.

Recommended Resolution

For testing:

--radial-samples 128 --height-samples 64

For a smoother final model:

--radial-samples 256 --height-samples 128

For very smooth surfaces:

--radial-samples 512 --height-samples 256

Higher resolutions create significantly more triangles.

How It Works

The interlocking surface is based on a mathematical function:

r(θ,z) = R + A sin(kz + nθ)

where:

• R is the base radius
• A is the wave amplitude
• k controls the vertical waves
• n controls the angular twisting

The surface is sampled directly and converted into a triangle mesh.

This is different from voxel-based generation.

Voxel approach

Model
  ↓
Voxel grid
  ↓
Marching cubes
  ↓
STL

This can produce stepped or blocky surfaces depending on voxel resolution.

This approach

Mathematical surface
  ↓
Direct surface sampling
  ↓
Triangle mesh
  ↓
STL

The underlying interface is therefore a continuous mathematical curve, with the STL triangles only approximating that curve.

Input Models

The input should preferably be:

• Watertight
• A single solid
• A reasonably clean mesh
• Suitable for boolean operations

For example:

model.stl

or:

model.obj

A model containing holes, self-intersections, or disconnected geometry may produce incorrect results.

Output

inner.stl contains the inner piece.

outer.stl contains the outer piece.

combined.stl contains both meshes in their generated positions and is useful for checking the result in a slicer or mesh viewer.

The two individual STLs should normally be exported separately for printing.

Printing

The generated parts are intended to be printed as separate pieces.

The most important setting is clearance. A printer with poorer dimensional accuracy may require a larger clearance.

A reasonable first test is:

Clearance: 0.3 mm

If the pieces are too tight:

0.4–0.5 mm

If they are excessively loose:

0.2–0.25 mm