Skip to content

kumiki.stl

Flat import path

kumiki/__init__.py re-exports everything on this page via from kumiki import *, so every name below is also available directly as kumiki.STLTimber -- you do not need to import from the submodule path shown in the heading above.

kumiki.stl

STL stock, timber-local placement, and source-call provenance.

STLTimber dataclass

STLTimber(*, stl_path: str, mesh: TriangleSolid, placement: Optional[STLPlacement] = None, source: Optional[STLSource] = None, units: str = 'mm')

Bases: MeshTimber

Represent STL stock, or a reference prism awaiting placement when placement is None.

stl_path class-attribute instance-attribute

stl_path: str = field(kw_only=True)

mesh class-attribute instance-attribute

mesh: TriangleSolid = field(kw_only=True, repr=False)

placement class-attribute instance-attribute

placement: Optional[STLPlacement] = field(default=None, kw_only=True)

source class-attribute instance-attribute

source: Optional[STLSource] = field(default=None, kw_only=True, repr=False, compare=False)

units class-attribute instance-attribute

units: str = field(default='mm', kw_only=True)

needs_stl_placement property

needs_stl_placement: bool

placed_mesh

placed_mesh() -> TriangleSolid
Source code in kumiki/stl.py
def placed_mesh(self) -> TriangleSolid:
    import numpy as np
    vertices = np.asarray(self.mesh.vertices)
    matrix = (self.placement or STLPlacement()).matrix()
    placed = vertices @ matrix[:3, :3].T + matrix[:3, 3]
    return replace(self.mesh, vertices=tuple(tuple(float(v) for v in p) for p in placed), label=self.csg_label('rough'))

is_perfect_timber

is_perfect_timber() -> bool
Source code in kumiki/stl.py
def is_perfect_timber(self) -> bool:
    return self.needs_stl_placement

get_rough_half_sizes

get_rough_half_sizes()
Source code in kumiki/stl.py
def get_rough_half_sizes(self):
    if self.needs_stl_placement:
        return super().get_rough_half_sizes()
    bounds = self.placed_mesh().get_aabb()
    assert bounds.max_x is not None and bounds.min_x is not None
    assert bounds.max_y is not None and bounds.min_y is not None
    return (create_v2(max(0, bounds.max_x), max(0, -bounds.min_x)),
            create_v2(max(0, bounds.max_y), max(0, -bounds.min_y)))

get_actual_csg_local

get_actual_csg_local(with_feature_labels: bool = True)
Source code in kumiki/stl.py
def get_actual_csg_local(self, with_feature_labels: bool = True):
    if self.needs_stl_placement:
        return super().get_extended_actual_csg_local(False, False, with_feature_labels)
    return self.placed_mesh()

get_extended_actual_csg_local

get_extended_actual_csg_local(extend_bot: bool, extend_top: bool, with_feature_labels: bool = True)
Source code in kumiki/stl.py
def get_extended_actual_csg_local(self, extend_bot: bool, extend_top: bool, with_feature_labels: bool = True):
    return self.get_actual_csg_local(with_feature_labels)

STLPlacement dataclass

STLPlacement(translation: Sequence[float] = (0, 0, 0), rotation: Sequence[float] = (0, 0, 0), scale: Sequence[float] = (1, 1, 1))

Place a mesh in timber-local space: scale, XYZ Euler rotation in degrees, then translation in metres.

translation class-attribute instance-attribute

translation: Sequence[float] = (0, 0, 0)

rotation class-attribute instance-attribute

rotation: Sequence[float] = (0, 0, 0)

scale class-attribute instance-attribute

scale: Sequence[float] = (1, 1, 1)

__post_init__

__post_init__()
Source code in kumiki/stl.py
def __post_init__(self):
    for name in ('translation', 'rotation', 'scale'):
        values = tuple(float(v) for v in getattr(self, name))
        if len(values) != 3 or not all(math.isfinite(v) for v in values):
            raise ValueError(f"STL {name} must contain three finite numbers")
        if name == 'scale' and any(v <= 0 for v in values):
            raise ValueError('STL scales must be positive')
        object.__setattr__(self, name, values)

to_dict

to_dict()
Source code in kumiki/stl.py
def to_dict(self):
    return {name: list(getattr(self, name)) for name in ('translation', 'rotation', 'scale')}

matrix

matrix()
Source code in kumiki/stl.py
def matrix(self):
    import numpy as np
    from trimesh.transformations import euler_matrix
    # Three.js Euler XYZ composes Rx * Ry * Rz (rotating intrinsic axes).
    matrix = euler_matrix(*(math.radians(v) for v in self.rotation), axes='rxyz')
    matrix[:3, :3] = matrix[:3, :3] @ np.diag(self.scale)
    matrix[:3, 3] = self.translation
    return matrix

create_stl_timber

create_stl_timber(reference: PerfectTimberWithin, stl_path, *, units: str = 'mm', placement: Optional[Mapping[str, Sequence[float]]] = None) -> STLTimber

Load STL stock relative to this source file, using reference for joinery coordinates.

Omit placement to show a placeholder in Kigumi. Placement has translation (metres), rotation (XYZ degrees), and positive scale triples, all relative to the reference timber. STL stock cannot extend itself to accommodate end joints.

Source code in kumiki/stl.py
def create_stl_timber(reference: PerfectTimberWithin, stl_path, *, units: str = 'mm',
                      placement: Optional[Mapping[str, Sequence[float]]] = None) -> STLTimber:
    """Load STL stock relative to this source file, using `reference` for joinery coordinates.

    Omit placement to show a placeholder in Kigumi. Placement has translation (metres),
    rotation (XYZ degrees), and positive scale triples, all relative to the reference timber.
    STL stock cannot extend itself to accommodate end joints.
    """
    current = inspect.currentframe()
    caller = current.f_back if current else None
    assert caller is not None, "STL source resolution requires a Python caller frame"
    try:
        source_path = Path(caller.f_code.co_filename).resolve()
        source = _source_call(source_path, caller.f_lineno)
    finally:
        del caller, current
    path = Path(stl_path)
    if not path.is_absolute():
        path = source_path.parent / path
    configured = None if placement is None else STLPlacement(**placement)
    return STLTimber(length=reference.length, size=reference.size, transform=reference.transform,
                     ticket=reference.ticket, stl_path=str(path.resolve()), mesh=load_stl(path, units),
                     placement=configured, source=source, units=units)