[family-assembly] Add t_handle_ball_lock_pin

[jiashunwu1030-oss]

Family

• Family: t_handle_ball_lock_pin
• Type: multi-body family / assembly
• Closes [family-assembly] t_handle_ball_lock_pin #53
• Product: Elesa+Ganter GN 113.8 T-handle Ball Lock Pin
• Summary: Table-driven CadQuery model of the externally visible locked state, with a stainless pin, plastic T-handle, push button, and two locking balls.

Official manufacturer reference — copied from Family Issue #53

The primary official GN 113.8 datasheet page below contains the manufacturer product photo and dimensioned drawing.

---

Generated — benchmark views (what the model sees)

The four benchmark viewing directions for the submitted family:

Generated — easy / medium / hard samples

The deterministic difficulty samples used for the family preview:

Extremes — smallest & largest sampled instances

The left model is GN 113.8-5-10; the right model is GN 113.8-25-150.

Modeled external bodies — medium seed 0

catalog_index 18 — GN 113.8-12-20

The image separates the five actual modeled bodies:

1. Stainless pin shaft with locking-ball pockets
2. Plastic T-handle with integrated hub/shoulder
3. External push button
4. Upper locking ball
5. Lower locking ball

The upper and lower locking balls are two distinct assembly instances.

Schematic exploded / assembly sequence

Schematic exploded/assembly sequence of the five modeled external bodies; not an authoritative manufacturing procedure.

The final stage matches the locked state returned by part.py. Hidden springs, push rods, and the internal actuator are not modeled. The image shows only the relative positions of the five modeled external bodies and does not claim to reproduce a manufacturer-specified assembly process.

Button input and locking-ball motion — schematic

Schematic operating states of the modeled external bodies. The hidden actuator mechanism is omitted; button travel and intermediate motion are not manufacturer-specified dimensions.

Button input and ball retraction are functionally associated through an omitted internal mechanism; direct contact is not modeled.

For this GN 113.8-12-20 example, d1 = 12 mm and d2 = 14.5 mm. The per-side locked protrusion shown is the geometric envelope difference (d2-d1)/2 = 1.25 mm; it is not claimed as the manufacturer-specified physical ball travel. The illustrated button displacement is schematic and is not an official catalog dimension.

How it's parameterized

• catalog_index selects one complete manufacturer row; dimensions are never independently mixed into catalog combinations that do not exist.
• The family covers 30 reviewed catalog designations from GN 113.8-5-10 through GN 113.8-25-150.
• Exact table-driven dimensions are d1, l1, d2, d3, d4, l2, l3, and m.
• Datasheet tolerances recorded in issue [family-assembly] t_handle_ball_lock_pin #53 are d1 -0.04/-0.08, l1 +0.6, and l2 ±1 mm.
• catalog_index 18 / GN 113.8-12-20 is the deterministic medium seed 0 sample. Its modeled shaft length is l1+l2 = 20+10.6 = 30.6 mm.
• The model declares "solids": 5 and returns five non-degenerate visible bodies: the pin shaft with locking-ball pockets, the T-handle with integrated hub/shoulder, the external push button, and two locking-ball instances.
• The push button is coaxial with the pin but remains a separate short, stepped, edge-chamfered body seated in an annular-clearance bore.
• The plastic T-handle is reconstructed from both manufacturer orthographic outlines: curved upper/lower wings and the central button recess come from the side view, while the rounded eye-shaped envelope and two key-ring slots come from the end view.
• The catalog envelopes control pin diameter, grip length, locked ball envelope, handle height, neck diameter, tip-to-ball distance, handle length, and handle thickness.

Verification (every sampled instance — five non-degenerate solids)

difficulty	seed	catalog_index	catalog designation	d1	l1	d2	d3	l3	solids	valid	bbox (mm)
easy	0	8	GN 113.8-8-10	8	10	9.5	48	31	5	yes	49×21×48
easy	1	4	GN 113.8-6-10	6	10	7	40	25	5	yes	42×16×40
easy	2	8	GN 113.8-8-10	8	10	9.5	48	31	5	yes	49×21×48
easy	3	8	GN 113.8-8-10	8	10	9.5	48	31	5	yes	49×21×48
easy	4	7	GN 113.8-6-80	6	80	7	40	25	5	yes	112×16×40
medium	0	18	GN 113.8-12-20	12	20	14.5	58	36.5	5	yes	67×28×58
medium	1	14	GN 113.8-10-30	10	30	12	48	31	5	yes	71×21×48
medium	2	18	GN 113.8-12-20	12	20	14.5	58	36.5	5	yes	67×28×58
medium	3	18	GN 113.8-12-20	12	20	14.5	58	36.5	5	yes	67×28×58
medium	4	17	GN 113.8-10-120	10	120	12	48	31	5	yes	161×21×48
hard	0	27	GN 113.8-20-150	20	150	25	80	46.5	5	yes	217×38×80
hard	1	24	GN 113.8-16-150	16	150	19	58	36.5	5	yes	201×28×58
hard	2	27	GN 113.8-20-150	20	150	25	80	46.5	5	yes	217×38×80
hard	3	27	GN 113.8-20-150	20	150	25	80	46.5	5	yes	217×38×80
hard	4	29	GN 113.8-25-150	25	150	30.8	80	46.5	5	yes	219×38×80

bench2 validate t_handle_ball_lock_pin --seeds 5 → PASS.

Validation results

Check	Result
family.json, base plane, parameter contract	PASS
Easy sampling and execution	5/5 PASS
Medium sampling and execution	5/5 PASS
Hard sampling and execution	5/5 PASS
Catalog coverage	All 30 indices reached
Difficulty separation	PASS
Geometry novelty	9/15 unique shapes (40%)
Multi-body geometry	5 non-degenerate solids per instance
Ruff code check	PASS
GitHub validate-designs / validate	PASS

Modeling simplifications and constraints

• All 30 catalog_index mappings come from complete rows in the official manufacturer catalog.
• catalog_index 18 / GN 113.8-12-20 is medium seed 0, and its shaft length is l1+l2 = 30.6 mm.
• The family represents the externally visible locked state.
• The manufacturer does not dimension the handle curves, push-button geometry, locking-ball diameter, or ball-pocket geometry. Those features use the explicit drawing-derived proportion rules already declared in family.json and part.py; they are not presented as exact catalog dimensions.
• The hidden spring, actuator rod, and internal mechanism are intentionally omitted because complete internal dimensions are not provided.
• The operating-state image shows only the functional association between button input and ball retraction; it does not claim an exact internal mechanism or manufacturer-specified motion.
• No unsupported threads, holes, grooves, or hidden mechanisms were added.

Delivered files

• part.py — CadQuery geometry
• spec.py — 30 complete catalog rows, parameter contract, and constraints
• family.json — provenance, description, contributor, and solids: 5
• preview.png — difficulty overview
• preview_views.png — four benchmark views
• preview_extremes.png — global minimum and maximum

Checklist

• bench2 validate t_handle_ball_lock_pin --seeds 5 passes; CI validation also passes.
• All three standard preview images are present.
• family.json declares "solids": 5, and every entity is non-degenerate.
• All 30 catalog mappings remain complete manufacturer combinations.
• The PR code scope remains limited to this family and its six required package files.
• The three additional explanatory images are GitHub user-attachments, not repository delivery files.
• Every PARAM_SPEC.source and every check() constraint cites the manufacturer table, a physical constraint, or honestly says "proportion".
• Reference drawings, product photos, and the datasheet remain in issue [family-assembly] t_handle_ball_lock_pin #53 rather than the repository.
• The commit is DCO-signed.
• AI-assisted; the contributor reviewed the model, constraints, validation data, and rendered evidence.

Sources used

• Elesa+Ganter, GN 113.8 T-handle Ball Lock Pin manufacturer datasheet, 5/2026: https://www.elesa-ganter.com/siteassets/PDF/EN/GN%20113.8.pdf
• Family source record and the 30 selected official catalog rows: [family-assembly] t_handle_ball_lock_pin #53

[github-actions]

Welcome, and thanks for the family PR! Three things that answer most questions:

• No checks running? A maintainer must click Approve workflows once for your first PR — pending, not ignored.
• Red gate? The message tells you the fix: click Details, or read the bench2 validate report comment posted after each run. Reproduce locally with uv sync && uv run bench2 validate <family> (debug help).
• Scope: designs/<family>/ holds only the package files (reference drawings/photos go in the family issue), and the PR checklist must be fully ticked. Not done yet? Mark the PR as a Draft.

中文:红 ✗ 点 Details 或看 validate 报告评论;本地 uv run bench2 validate <family> 复现;参考图放 issue 不放 PR;没做完用 Draft。入门 → GETTING_STARTED.zh

[github-actions]

bench2 validate

t_handle_ball_lock_pin

  ✓ family.json: keys + base_plane valid
  ✓ pieces: build(9 params) + PARAM_SPEC + check present
  ✓ PARAM_SPEC: 9 params, all entries complete
  ✓ easy: 4/4 seeds sample+check+build+execute clean
  ✓ medium: 4/4 seeds sample+check+build+execute clean
  ✓ hard: 4/4 seeds sample+check+build+execute clean
  ✓ coverage: catalog_index reaches all 30 declared values (standard table fully covered)
  ✓ difficulty separation: difficulties produce distinct programs
  ✓ geometry novelty: 6/12 unique shapes (50% duplicate)
  ✓ solids: every instance non-degenerate, 5 solid(s) each (declares solids=5)
PASS — designs/t_handle_ball_lock_pin

Previews: the previews artifact on this run.

[HaozheZhang6]

For assembly case, we also need the render img for each part and a picture showing how it is assembled.

[HaozheZhang6]

please also copy the reference picture and drawing from issue

[HaozheZhang6]

looks good to me