pip-hinge 0.1.0__py3-none-any.whl

pip_hinge/__init__.py

@@ -0,0 +1,420 @@
+"""Parametric print-in-place piano hinge for clamshell cases.
+
+Four inputs, everything else derived:
+
+  * ``case_h``        wall height of the case half (mm)
+  * ``hinge_length``  total hinge length along its axis (mm)
+  * ``stations``      number of alternating cs/ps tabs (even, ≥ 2)
+  * ``knuckle``       Knuckle.FULL  → Po = 2 × case_h, knuckle rests on bed,
+                                       no ramp needed
+                      Knuckle.HALF  → Po = case_h, 45°-or-shallower ramp,
+                                       prints supportless
+
+The implicit constraints are documented in docs/clamshell-integration.md and
+the diagrams under docs/diagrams/. Two leftover dimensional knobs are exposed
+for tuning the pin/bore feel (``pivot_clearance``, ``clasp_clearance``) and
+three small pin-engagement constants are kept tunable for backwards
+compatibility with the original FreeCAD source.
+
+Derived from "Parametric print-in-place hinge. FreeCAD." by r0berts
+(https://www.printables.com/model/1395662-parametric-print-in-place-hinge-freecad),
+licensed CC BY 4.0.
+
+Print orientation: lay flat on the bed, hinge axis along Y (parallel to bed).
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+from build123d import (
+    Axis,
+    CenterArc,
+    Circle,
+    Compound,
+    Line,
+    Plane,
+    Polyline,
+    Pos,
+    Sketch,
+    extrude,
+    make_face,
+    revolve,
+)
+from OCP.BRep import BRep_Builder
+from OCP.TopoDS import TopoDS_Compound
+
+
+class Knuckle(Enum):
+    """Knuckle size.
+
+    FULL and HALF are percentages of the closed-case height (2 × case_h);
+    SMALL is computed in ``_resolve()`` as max(case_h/2, 5 mm) — the 1/4-of-FULL
+    ratio with a 5 mm absolute floor that keeps the bore + pin big enough to
+    print reliably on a 0.4 mm-nozzle FDM regardless of case height.
+    """
+
+    FULL = 100   # Po = 2 × case_h; knuckle bottom touches bed, no ramp needed
+    HALF = 50    # Po = case_h; 45°-or-shallower self-supporting ramp
+    SMALL = -1   # sentinel — see _resolve() for the actual size formula
+
+
+@dataclass(frozen=True)
+class HingeParams:
+    """User-facing parameters for the print-in-place hinge."""
+
+    case_h: float                        # case wall height (mm)
+    hinge_length: float                  # total hinge length along the axis (mm)
+    stations: int = 6                    # alternating cs/ps tab count (even, ≥ 2)
+    knuckle: Knuckle = Knuckle.FULL      # knuckle size
+    mounting_flat: float = 0.5           # flat width past the disc edge (mm)
+    pivot_clearance: float = 0.6         # radial pin/bore gap (mm)
+    pivot_z_offset: float = 0.2
+    """Empirical lift of the hinge axis above the case wall top (mm).
+
+    The leaf grows by this much in Z so the bed-side end of the leaf
+    still lands on the bed when the lifted axis is positioned at
+    ``case_h``; the bottom face of the disc sits ``pivot_z_offset``
+    above the wall top. When the case closes, the lid then sits
+    ``2 × pivot_z_offset`` above the base instead of meeting it on a
+    zero-tolerance plane — so a high spot anywhere along the seam
+    can't spring the front of the case open under elastic tension.
+
+    Default 0.2 mm matches the empirical value baked into the previous
+    clamshell example. Set to 0 to disable (knuckle bottom rests
+    directly on the wall top, no seam gap).
+    """
+    clasp_clearance: Optional[float] = None
+    """Axial gap between cs and ps tabs (mm).
+
+    Leave as ``None`` to auto-scale with knuckle diameter ``Po``: 0.2 mm
+    at Po = 5 mm (matches the original r0berts FreeCAD value — the tighter
+    fit matters more when the knuckle is small), linearly up to 0.4 mm at
+    Po ≥ 10 mm (the relaxed value that prints reliably on a standard
+    0.4 mm-nozzle FDM). Formula: ``clamp(0.04 × Po, 0.2, 0.4)``. Pass an
+    explicit value to override.
+    """
+
+    # Pin-engagement constants hand-tuned in the original FreeCAD source.
+    # Leave at defaults unless deliberately tweaking pin feel.
+    pin_cyl_extra: float = 1.5
+    pin_end_offset: float = 0.5
+    pin_short_cyl_factor: float = 1 / 3
+
+    def _resolve(self) -> dict:
+        if self.case_h <= 0:
+            raise ValueError(f"case_h must be > 0 (got {self.case_h})")
+        if self.hinge_length <= 0:
+            raise ValueError(f"hinge_length must be > 0 (got {self.hinge_length})")
+        if self.stations < 2 or self.stations % 2 != 0:
+            raise ValueError(
+                f"stations must be an even integer ≥ 2 (got {self.stations})"
+            )
+        if self.mounting_flat <= 0:
+            # W == Ro at 0 gives a degenerate leaf profile that OCC rejects with a
+            # cryptic StdFail_NotDone; fail early with a clear message instead.
+            raise ValueError(f"mounting_flat must be > 0 (got {self.mounting_flat})")
+        if self.pivot_z_offset < 0:
+            raise ValueError(f"pivot_z_offset must be ≥ 0 (got {self.pivot_z_offset})")
+
+        # Knuckle is sized to the LIFTED axis (case_h + pivot_z_offset), not just
+        # case_h. This preserves the "FULL knuckle bottom rests on bed when flat
+        # for printing" guarantee: with Ro = case_h + pz_off, the axis at Z =
+        # case_h + pz_off and Ro the same means the disc bottom lands at exactly
+        # Z = 0 (the bed). It also keeps the bottom segment of the leaf polyline
+        # horizontal at FULL (no spurious slope from the offset).
+        effective_case_h = self.case_h + self.pivot_z_offset
+        if self.knuckle is Knuckle.SMALL:
+            # 1/4 of FULL, floored at 5 mm so the pin & bore stay printable
+            # at any case height. For case_h ≥ 10 mm the ratio dominates;
+            # below that the 5 mm floor kicks in.
+            Po = max(effective_case_h / 2, 5.0)
+        else:
+            Po = 2 * effective_case_h * self.knuckle.value / 100
+        Ro = Po / 2
+        Pi = Po / 2                                  # bore diameter (= Ro)
+        if Pi <= self.pivot_clearance:
+            raise ValueError(
+                f"bore Ø ({Pi:.2f}) ≤ pivot_clearance ({self.pivot_clearance}); "
+                f"increase case_h or reduce pivot_clearance"
+            )
+
+        Cw = self.hinge_length / self.stations
+        if Cw < 3:
+            warnings.warn(
+                f"clasp_width = {Cw:.2f}mm is below ~3mm; likely too thin for FDM. "
+                f"Reduce stations or increase hinge_length.",
+                stacklevel=2,
+            )
+
+        # Size-aware clasp_clearance default: scales linearly with knuckle
+        # diameter Po, from 0.2 mm at Po=5 mm to 0.4 mm at Po≥10 mm. The
+        # tighter fit matters more when the knuckle is small (relative
+        # play is bigger). Clamped both ends so very small or very large
+        # knuckles stay in the printable / sensible range.
+        if self.clasp_clearance is None:
+            Cc = max(0.2, min(0.4, 0.04 * Po))
+        else:
+            Cc = self.clasp_clearance
+        return {
+            "case_h": self.case_h,
+            "H": self.hinge_length,
+            "stations": self.stations,
+            "Po": Po,
+            "Ro": Ro,
+            "T": Ro,                                 # T = Ro by construction
+            "Pi": Pi,
+            "Pc": self.pivot_clearance,
+            "W": Ro + self.mounting_flat,
+            "Cw": Cw,
+            "Cc": Cc,
+            "pivot_z_offset": self.pivot_z_offset,
+            "pin_cyl_extra": self.pin_cyl_extra,
+            "pin_end_offset": self.pin_end_offset,
+            "pin_short": self.pin_short_cyl_factor,
+        }
+
+
+# ── pocket polylines (parametric in N stations) ───────────────────────────────
+
+def _cs_pocket_polyline(N: int, Cw: float, Cc: float, Xi: float, Xo_cs: float):
+    """Pocket cut for the cs (cylinder-side) leaf. Excludes N/2 cs tabs.
+
+    cs tabs (with bores in them) sit at Y centres spaced 2·Cw apart,
+    symmetric around Y = 0. Each tab is Cw − Cc wide (the Cc/2 margin
+    per side is the printable clearance between meshing cs and ps tabs).
+    """
+    k = N // 2
+    half_tab = (Cw - Cc) / 2
+    pad_max = (N + 1) * Cw / 2 + Cc / 2     # extends slightly past H/2
+
+    pts = [(Xo_cs, pad_max), (Xo_cs, -pad_max), (Xi, -pad_max)]
+    cs_centres = [(-(k - 1) + 2 * i) * Cw for i in range(k)]
+    for Y_c in cs_centres:                  # ascending Y
+        pts.extend([
+            (Xi,  Y_c - half_tab),
+            (-Xi, Y_c - half_tab),
+            (-Xi, Y_c + half_tab),
+            (Xi,  Y_c + half_tab),
+        ])
+    pts.extend([(Xi, pad_max), (Xo_cs, pad_max)])
+    return Polyline(*pts)
+
+
+def _ps_pocket_polyline(N: int, Cw: float, Xi: float, Xo_ps: float):
+    """Pocket cut for the ps (pin-side) leaf. Excludes ps end-caps + middle tabs.
+
+    Pattern along Y: ps_end_cap (Cw/2) | cs (Cw) | ps_middle (Cw) | cs | ... | ps_end_cap.
+    The ends are half-width ps caps; in between, full-Cw alternating cs/ps tabs,
+    starting and ending with cs.
+    """
+    k = N // 2
+    ps_outer = (k - 0.5) * Cw                # inner edge of the ps end-caps
+    ps_centres = [(-(k - 2) + 2 * i) * Cw for i in range(k - 1)]
+
+    pts = [
+        (-Xi,   -ps_outer),
+        (Xo_ps, -ps_outer),
+        (Xo_ps,  ps_outer),
+        (-Xi,    ps_outer),
+    ]
+    for Y_c in reversed(ps_centres):         # walk back down with notches
+        pts.extend([
+            (-Xi, Y_c + Cw / 2),
+            (Xi,  Y_c + Cw / 2),
+            (Xi,  Y_c - Cw / 2),
+            (-Xi, Y_c - Cw / 2),
+        ])
+    pts.append((-Xi, -ps_outer))
+    return Polyline(*pts)
+
+
+# ── pin segments (parametric in N stations) ───────────────────────────────────
+
+def _pin_loops(N: int, Cw: float, Rp: float,
+               pin_cyl_extra: float, pin_end_offset: float, pin_short: float):
+    """2D pin profiles to be revolved around Y axis.
+
+    One long capsule per ps middle tab (N/2 − 1 of them) plus a bullet at each
+    end-cap (always 2). For N = 2 there are no middle tabs, so just 2 bullets.
+    """
+    k = N // 2
+    long_centres = [(-(k - 2) + 2 * i) * Cw for i in range(k - 1)]
+    cyl_long = Cw + pin_cyl_extra
+    half_long = cyl_long / 2
+
+    loops = []
+    for Y_c in long_centres:
+        y_top = Y_c + half_long
+        y_bot = Y_c - half_long
+        y_cap_t = y_top + Rp
+        y_cap_b = y_bot - Rp
+        loops.append(
+            Line((Rp, y_top), (Rp, y_bot))
+            + CenterArc(center=(0, y_bot), radius=Rp, start_angle=360, arc_size=-90)
+            + Line((0, y_cap_b), (0, y_cap_t))
+            + CenterArc(center=(0, y_top), radius=Rp, start_angle=90, arc_size=-90)
+        )
+
+    # End-cap bullets: hemisphere on the inner end (pointing toward the centre),
+    # flat top buried inside the ps end-cap material.
+    end_inner = (k - 0.5) * Cw
+    cyl_short = Cw * pin_short
+    y_short_cyl_b = end_inner - pin_end_offset
+    y_short_cyl_t = y_short_cyl_b + cyl_short
+    y_short_cap_b = y_short_cyl_b - Rp
+
+    loops.append(                            # +Y end
+        Polyline(
+            (0, y_short_cyl_t),
+            (Rp, y_short_cyl_t),
+            (Rp, y_short_cyl_b),
+        )
+        + CenterArc(center=(0, y_short_cyl_b), radius=Rp, start_angle=0, arc_size=-90)
+        + Line((0, y_short_cap_b), (0, y_short_cyl_t))
+    )
+    loops.append(                            # −Y end (mirror)
+        CenterArc(center=(0, -y_short_cyl_b), radius=Rp, start_angle=0, arc_size=90)
+        + Polyline(
+            (0, -y_short_cap_b),
+            (0, -y_short_cyl_t),
+            (Rp, -y_short_cyl_t),
+            (Rp, -y_short_cyl_b),
+        )
+    )
+    return loops
+
+
+# ── main constructor ──────────────────────────────────────────────────────────
+
+def make_hinge(params: HingeParams = None) -> Compound:
+    """Build the full print-in-place hinge as a 2-body Compound."""
+    if params is None:
+        params = HingeParams(case_h=10.0, hinge_length=60.0)
+    p = params._resolve()
+    case_h, H, N = p["case_h"], p["H"], p["stations"]
+    pz_off = p["pivot_z_offset"]
+    # The hinge is built in coords where the disc centre is at Z=0; after
+    # construction we translate everything up by pz_off so the disc centre
+    # ends up at the lifted axis height when the caller positions the hinge
+    # to the wall top. The leaf must therefore extend down to Z = -leaf_h
+    # = -(case_h + pz_off), so its bed-side end lands at world Z = 0.
+    leaf_h = case_h + pz_off
+    Ro, T, Po = p["Ro"], p["T"], p["Po"]
+    Pi, Pc, W = p["Pi"], p["Pc"], p["W"]
+    Cw, Cc = p["Cw"], p["Cc"]
+
+    Ri = Pi / 2                              # bore radius
+    Rp = Ri - Pc / 2                         # pin radius
+    Xi = Ro + Pc                             # inner X boundary of pocket comb
+    pocket_extrude = leaf_h + Pc / 2
+
+    # ── leaf profiles ────────────────────────────────────────────────────────
+    # Each leaf's underside must reach the bed self-supporting (no slicer support).
+    # The knuckle disc sits at the wall top; on the MESHING side (the side with no
+    # wall under it) its lower arc faces down and would sag. Two cases:
+    #
+    #  • small disc -> a tangent RAMP from the wall foot (±W, -leaf_h) up to the far
+    #    tangent point cradles the underside; the exposed arc above is steeper still.
+    #    The tangent is the steepest ramp that reaches the disc, so for a small disc
+    #    it is >= 45° from horizontal and self-supports.
+    #
+    #  • big disc (e.g. Knuckle.HALF) -> that foot-anchored tangent comes out < 45°
+    #    and would sag. Instead the support line meets the disc TANGENTIALLY on the
+    #    meshing side at exactly SELF_SUPPORT_DEG and runs down to its own bed
+    #    contact, replacing the disc's downward arc with a self-supporting TEARDROP.
+    #
+    #  • FULL -> the disc rests on the bed (no ramp, no teardrop).
+    SELF_SUPPORT_DEG = 45.0
+    use_tangent = T < leaf_h - 1e-6
+
+    def _far_tangent(wall_x):
+        """Angle (rad) of the tangent point on the side OPPOSITE the wall."""
+        ex, ey = wall_x, -leaf_h
+        d = math.hypot(ex, ey)
+        a = math.asin(min(1.0, Ro / d))
+        base = math.atan2(ey, ex)
+        for s in (1.0, -1.0):
+            th = base + s * (math.pi / 2 - a)
+            if (math.cos(th) < 0) == (wall_x > 0):     # far side = opposite the wall
+                return th
+        return None
+
+    def _knuckle_geo(wall_x):
+        """('ramp'|'teardrop', tangent_angle_rad) for the meshing-side underside."""
+        th = _far_tangent(wall_x)
+        if th is not None:
+            tp = (Ro * math.cos(th), Ro * math.sin(th))
+            ang = math.degrees(math.atan2(abs(tp[1] + leaf_h), abs(tp[0] - wall_x)))
+            if ang >= SELF_SUPPORT_DEG:
+                return "ramp", th
+        # teardrop: meshing-side tangent at exactly the self-support angle
+        th_td = math.radians(180.0 + SELF_SUPPORT_DEG) if wall_x > 0 \
+            else math.radians(360.0 - SELF_SUPPORT_DEG)
+        return "teardrop", th_td
+
+    def _leaf_profile(wall_x):
+        """Outer profile: wall + self-supporting underside + exposed disc arc."""
+        sgn = 1.0 if wall_x > 0 else -1.0
+        eq = (sgn * Ro, 0.0)                           # disc equator on the wall side
+        bed = []
+        if not use_tangent:                            # FULL: disc rests on the bed
+            tp, start = (0.0, -T), 270.0
+        else:
+            mode, th = _knuckle_geo(wall_x)
+            tp = (Ro * math.cos(th), Ro * math.sin(th))
+            start = math.degrees(th) % 360.0
+            if mode == "teardrop":                     # tangent line down to its own
+                run = (leaf_h + tp[1]) / math.tan(math.radians(SELF_SUPPORT_DEG))
+                bed = [(tp[0] + sgn * run, -leaf_h)]   # bed contact, then up to tp
+        # arc sweeps from the tangent point over the EXPOSED side back to the equator
+        arc = -start if wall_x > 0 else 540.0 - start
+        return (Polyline(eq, (wall_x, 0.0), (wall_x, -leaf_h), *bed, tp)
+                + CenterArc(center=(0, 0), radius=Ro, start_angle=start, arc_size=arc))
+
+    cs_profile = _leaf_profile(W)
+    cs_sketch = Sketch() + Plane.XZ * (make_face(cs_profile) - Circle(Ri))
+    cs_pad = extrude(cs_sketch, amount=H / 2, both=True)
+    # Pocket polygon left edge must stay left of the notch jogs (which go to -Xi),
+    # otherwise the polyline self-intersects and OCC misclassifies the interior.
+    # Old defaults happened to satisfy Xi − W ≤ −Xi; the new API's small W doesn't.
+    Xo_cs = min(Xi - W, -Xi - 1.0)
+    cs_pocket = make_face(_cs_pocket_polyline(N, Cw, Cc, Xi, Xo_cs))
+    cylinder_side = cs_pad - extrude(cs_pocket, amount=pocket_extrude, both=True)
+
+    # ── ps (pin-side) leaf ───────────────────────────────────────────────────
+    ps_profile = _leaf_profile(-W)
+    ps_sketch = Sketch() + Plane.XZ * make_face(ps_profile)
+    ps_pad = extrude(ps_sketch, amount=H / 2, both=True)
+    Xo_ps = 4 * Po - Xi
+    ps_pocket = make_face(_ps_pocket_polyline(N, Cw, Xi, Xo_ps))
+    pin_side = ps_pad - extrude(ps_pocket, amount=pocket_extrude, both=True)
+
+    # ── pin segments ────────────────────────────────────────────────────────
+    loops = _pin_loops(N, Cw, Rp, p["pin_cyl_extra"], p["pin_end_offset"], p["pin_short"])
+    pin_sketch = make_face(loops[0])
+    for loop in loops[1:]:
+        pin_sketch = pin_sketch + make_face(loop)
+    pin_side = pin_side + revolve(pin_sketch, axis=Axis.Y, revolution_arc=-360)
+
+    # ── lift everything by pivot_z_offset so the axis sits above the
+    # leaf-top reference (= where the wall top will end up). Leaf top
+    # stays at local Z=0 (= wall top); axis ends up at Z=+pz_off.
+    if pz_off:
+        cylinder_side = Pos(0, 0, pz_off) * cylinder_side
+        pin_side = Pos(0, 0, pz_off) * pin_side
+
+    # ── assemble into a 2-body Compound ─────────────────────────────────────
+    builder = BRep_Builder()
+    occ = TopoDS_Compound()
+    builder.MakeCompound(occ)
+    for solid in [*cylinder_side.solids(), *pin_side.solids()]:
+        builder.Add(occ, solid.wrapped)
+    return Compound(occ)
+
+
+__all__ = ["HingeParams", "Knuckle", "make_hinge"]

pip_hinge-0.1.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: pip-hinge
+Version: 0.1.0
+Summary: Parametric print-in-place piano hinge for clamshell cases, in build123d
+Project-URL: Homepage, https://github.com/pzfreo/pip-hinge
+Project-URL: Issues, https://github.com/pzfreo/pip-hinge/issues
+Author-email: Paul Fremantle <pzfreo@gmail.com>
+License: Creative Commons Attribution 4.0 International (CC BY 4.0)
+        
+        This work is a derivative of "Parametric print-in-place hinge. FreeCAD." by
+        r0berts, published at:
+        
+            https://www.printables.com/model/1395662-parametric-print-in-place-hinge-freecad
+        
+        The original is licensed under CC BY 4.0. This derivative — a build123d Python
+        port with full reparameterisation of the sketch geometry — is released under the
+        same CC BY 4.0 license.
+        
+        Copyright:
+            Original design © r0berts (Printables: @r0berts_1183620)
+            build123d port and parameterisation © 2026 Paul Fremantle (pzfreo)
+        
+        You are free to:
+            Share — copy and redistribute the material in any medium or format
+            Adapt — remix, transform, and build upon the material for any purpose,
+                    even commercially
+        
+        Under the following terms:
+            Attribution — You must give appropriate credit, provide a link to the
+            license, and indicate if changes were made. You may do so in any
+            reasonable manner, but not in any way that suggests the licensor
+            endorses you or your use.
+        
+            No additional restrictions — You may not apply legal terms or
+            technological measures that legally restrict others from doing anything
+            the license permits.
+        
+        Full legal text:
+            https://creativecommons.org/licenses/by/4.0/legalcode
+        
+        Summary:
+            https://creativecommons.org/licenses/by/4.0/
+License-File: LICENSE
+Requires-Python: <3.14,>=3.10
+Requires-Dist: build123d>=0.6
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pip-hinge
+
+A parametric print-in-place piano hinge in [build123d](https://github.com/gumyr/build123d),
+designed for clamshell cases.
+
+Four inputs:
+
+```python
+from pip_hinge import HingeParams, Knuckle, make_hinge
+
+hinge = make_hinge(HingeParams(
+    case_h        = 10,             # case wall height (mm)
+    hinge_length  = 60,             # total hinge length along the axis (mm)
+    stations      = 6,              # alternating cs/ps tab count (even, ≥ 2)
+    knuckle       = Knuckle.FULL,   # FULL = "bump on top", no ramp needed
+))
+```
+
+`make_hinge()` returns a 2-body `Compound`: the cylinder-side leaf (with
+bored knuckle tabs) and the pin-side leaf (with the integral pin).
+
+## In context: a flat-open clamshell with HALF knuckle
+
+![clamshell with HALF knuckle and corner magnet pockets, flat-open print orientation](docs/diagrams/clamshell_half_preview.png)
+
+Built by [`examples/clamshell.py`](examples/clamshell.py) — case_h = 10mm,
+80 × 50 mm footprint, 60 mm hinge with `Knuckle.HALF`, plus four 6 × 3 mm
+corner magnet pockets to latch the case shut. Both halves print as one
+piece in the orientation shown. The example also emits a bare HALF/FULL
+variant (no magnets) for reference.
+
+## Parameter reference
+
+![parameters guide](docs/diagrams/parameters_guide.png)
+
+Cross-section (Panel A) shows the spatial parameters: `case_h` (wall
+height), `PIVOT_Z_OFFSET` (extra lift), `mounting_flat` (flat past the
+disc edge), plus the derived `Po`/`Ro`/`T`/`W` and the pin/bore inset.
+Top view (Panel B) shows `hinge_length`, `stations`, derived
+`clasp_width`, and `clasp_clearance` between meshing tabs.
+
+## The two knuckle options
+
+![knuckle options](docs/diagrams/knuckle_options.png)
+
+| `knuckle`      | knuckle diameter            | ramp                  | gap between case walls (flat-open) |
+| -------------- | --------------------------- | --------------------- | ---------------------------------- |
+| `Knuckle.FULL` | `2 × case_h`                | none — rests on bed   | `2 × (case_h + mounting_flat)`     |
+| `Knuckle.HALF` | `case_h`                    | 45° self-supporting teardrop | `case_h + 2 × mounting_flat`       |
+| `Knuckle.SMALL`| `max(case_h / 2, 5 mm)`     | ~25° from vertical (smaller knuckle → naturally steeper) | `max(case_h, 10mm) + 2 × mounting_flat` |
+
+See [docs/clamshell-integration.md](docs/clamshell-integration.md) for
+mounting, orientation, multi-hinge layouts, and the closed-vs-open view.
+
+## Provenance
+
+This is a port of **["Parametric print-in-place hinge. FreeCAD."](https://www.printables.com/model/1395662-parametric-print-in-place-hinge-freecad)**
+by **[r0berts](https://www.printables.com/@r0berts_1183620)** on Printables,
+licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+The original is a spreadsheet-driven FreeCAD model. This repository:
+
+1. Translates the FreeCAD geometry into build123d Python via
+   [fcd2b123d](https://github.com/pzfreo/fcd2b123d).
+2. Reparameterises around four case-designer-facing inputs (`case_h`,
+   `hinge_length`, `stations`, `knuckle`) with the original dimensional
+   relationships derived under the hood.
+3. Generalises the comb pattern (hardcoded 6 stations in the original) to
+   any even number of stations ≥ 2, and adds an optional
+   `Knuckle.HALF` mode with a self-supporting teardrop knuckle for cases
+   where a smaller knuckle is wanted.
+
+Per the CC BY 4.0 terms: design and dimensional relationships are
+r0berts'; modifications are the build123d port, the four-input API, and
+the configurable station count and ramp.
+
+## Quick start
+
+Install from this repo into your own project (until it's on PyPI):
+
+```bash
+uv pip install git+https://github.com/pzfreo/pip-hinge.git
+```
+
+Then in your build123d code:
+
+```python
+from pip_hinge import HingeParams, Knuckle, make_hinge
+
+hinge = make_hinge(HingeParams(
+    case_h=10, hinge_length=60, knuckle=Knuckle.FULL,
+))
+cylinder_side, pin_side = hinge.solids()    # or use _split_hinge_by_side helper
+```
+
+Or to play with it locally:
+
+```bash
+git clone https://github.com/pzfreo/pip-hinge.git && cd pip-hinge
+uv pip install -e .                          # editable install
+python examples/clamshell.py                 # writes clamshell_{full,half,small,magnets}.{step,stl}
+python examples/hinge_only.py                # writes the bare hinge_{full,half}.{step,stl}
+```
+
+## Parameters
+
+The four primary inputs:
+
+| Parameter      | Default        | Meaning                                                  |
+| -------------- | -------------- | -------------------------------------------------------- |
+| `case_h`       | (required)     | Case wall height; the hinge's "scale" reference          |
+| `hinge_length` | (required)     | Total hinge length along the axis (Y)                    |
+| `stations`     | 6              | Number of alternating cs/ps tabs (even, ≥ 2)             |
+| `knuckle`      | `Knuckle.FULL` | `FULL`, `HALF`, or `SMALL` — see the option table below |
+
+Three small tuneables:
+
+| Parameter         | Default | Meaning                                            |
+| ----------------- | ------- | -------------------------------------------------- |
+| `mounting_flat`   | 0.5     | Flat width past the disc edge for case-wall fusion. Below `pivot_clearance` (= 0.6 mm) the bare hinge fragments into multiple solids — fine when fused into a case, see docs |
+| `pivot_clearance` | 0.6     | Radial pin/bore gap (FDM tolerance)                |
+| `clasp_clearance` | `None`  | Axial gap between cs and ps tabs. `None` auto-scales with knuckle diameter `Po`: 0.2 mm at Po ≤ 5 mm (matches r0berts' original), linear up to 0.4 mm at Po ≥ 10 mm. Pass an explicit value to override |
+
+Plus three pin-engagement constants from the original FreeCAD source
+(`pin_cyl_extra`, `pin_end_offset`, `pin_short_cyl_factor`) — leave at
+defaults unless deliberately tuning the pin/bore feel.
+
+## Validation
+
+`make_hinge()` raises `ValueError` for hard geometric problems:
+- non-positive `case_h`, `hinge_length`, or `mounting_flat`
+- `stations < 2` or odd
+- bore Ø ≤ `pivot_clearance` (knuckle too small for the pivot clearance)
+
+And warns (`warnings.warn`) when:
+- `clasp_width = hinge_length / stations` drops below ~3 mm (too thin for FDM)
+
+## Printing
+
+Lay flat on the bed with the hinge axis along Y (parallel to bed).
+0.2 mm layers, fan on, brim recommended. After printing, gently flex the
+leaves to break the clearance gaps free.
+
+- **FULL** prints without any supports at any knuckle size — the knuckle
+  rests on the bed.
+- **HALF** prints without supports at any `case_h`: the meshing-side underside
+  meets the knuckle tangentially at 45° and runs to the bed as a self-supporting
+  teardrop, so the disc's downward arc is never left hanging.
+
+## How this was built
+
+The build123d code, API design discussions, station-count generalisation,
+self-supporting ramp, clamshell example, and documentation in this
+repository were produced through a paired design session with
+[Claude Code](https://claude.com/claude-code) (Anthropic's Claude Opus 4.7).
+I drove the design decisions — what the API should look like, which
+knuckle geometries to support, what trade-offs to accept — and Claude wrote
+the code, generated the diagrams, ran the verifications, and opened the
+PRs. The conversation is the source of truth for *why* the code looks the
+way it does; the commit history reflects the steps.
+
+The original FreeCAD geometry from r0berts is unchanged in its dimensional
+relationships — it was reparameterised, not redesigned. The Claude
+collaboration is on the build123d port and the case-designer-facing API
+built on top of it.
+
+## License
+
+This work is licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/),
+matching the upstream Printables source. See [LICENSE](LICENSE).
+
+When using or redistributing, please credit:
+
+- **r0berts** — original FreeCAD design ([Printables](https://www.printables.com/model/1395662-parametric-print-in-place-hinge-freecad))
+- **Paul Fremantle** (pzfreo) — build123d port, four-input parameterisation, station generalisation, and ramp option

pip_hinge-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+pip_hinge/__init__.py,sha256=mbBr-HY_lzXPkJVRfHr2So6N9407c5rrI0j0da7DLhY,18820
+pip_hinge-0.1.0.dist-info/METADATA,sha256=xaB_T_Hvc5P02rsTCuQCduLFsIXaSf0RH2aIUyUUGXo,10291
+pip_hinge-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pip_hinge-0.1.0.dist-info/licenses/LICENSE,sha256=0NyCkKTOxqKWlEnuqb9S5VHRUHRGgdQW-rLOrhXzKxM,1355
+pip_hinge-0.1.0.dist-info/RECORD,,

pip_hinge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pip_hinge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,35 @@
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+This work is a derivative of "Parametric print-in-place hinge. FreeCAD." by
+r0berts, published at:
+
+    https://www.printables.com/model/1395662-parametric-print-in-place-hinge-freecad
+
+The original is licensed under CC BY 4.0. This derivative — a build123d Python
+port with full reparameterisation of the sketch geometry — is released under the
+same CC BY 4.0 license.
+
+Copyright:
+    Original design © r0berts (Printables: @r0berts_1183620)
+    build123d port and parameterisation © 2026 Paul Fremantle (pzfreo)
+
+You are free to:
+    Share — copy and redistribute the material in any medium or format
+    Adapt — remix, transform, and build upon the material for any purpose,
+            even commercially
+
+Under the following terms:
+    Attribution — You must give appropriate credit, provide a link to the
+    license, and indicate if changes were made. You may do so in any
+    reasonable manner, but not in any way that suggests the licensor
+    endorses you or your use.
+
+    No additional restrictions — You may not apply legal terms or
+    technological measures that legally restrict others from doing anything
+    the license permits.
+
+Full legal text:
+    https://creativecommons.org/licenses/by/4.0/legalcode
+
+Summary:
+    https://creativecommons.org/licenses/by/4.0/