kumiki.joints.workshop.decorative_joints

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.cut_practice_roundover_decoration -- you do not need to import from the submodule path shown in the heading above.

kumiki.joints.workshop.decorative_joints

Kumiki - Decorative joint construction functions

cut_practice_roundover_decoration

cut_practice_roundover_decoration(timber: BlockLike, edges: List[TimberEdge], radius: Numeric) -> Joint

Cuts a roundover of radius radius along edges of timber. Short edges (edges on the timber ends) are at the declared length of the timber rather than the maybe_end_cut length (which is not known here). Note, this does not check if round radii overlap.

Source code in kumiki/joints/workshop/decorative_joints.py

def cut_practice_roundover_decoration(timber: BlockLike, edges: List[TimberEdge], radius: Numeric) -> Joint:
    """
    Cuts a roundover of radius `radius` along edges of timber.
    Short edges (edges on the timber ends) are at the declared length of the timber rather than the maybe_end_cut length (which is not known here).
    Note, this does not check if round radii overlap.
    """
    # A joint has to remove something, so there is no joint to make for no
    # edges -- the caller wanted nothing done.
    assert edges, "cut_practice_roundover_decoration needs at least one edge to round over"

    edge_cuts_global = [_roundover_cut_for_edge(timber, edge, radius) for edge in edges]

    negative_csg = adopt_csg(
        None,
        timber.transform,
        SolidUnion(children=edge_cuts_global, label=CutCSGLabel("roundover_decoration")),
    )

    cutting = Cutting(
        timber=timber,
        negative_csg=negative_csg,
        label=CutCSGLabel("roundover_decoration"),
    )
    return Joint(
        cuttings={timber.ticket.path: cutting},
        ticket=JointTicket(joint_type="roundover_decoration"),
    )

cut_practice_rounded_end_decoration

cut_practice_rounded_end_decoration(timber: BlockLike, rounded_face: TimberFace, rounded_end: TimberFace, radius: Numeric, distance_from_end: Numeric, lateral_offset: Numeric = 0) -> Joint

Rounds off rounded_end of timber with a single large-radius arc spanning the full width perpendicular to both rounded_face and rounded_end -- a gentle bowed/bullnose end profile, visible as a curved outline when looking straight at rounded_face (the arc's plane is perpendicular to rounded_face's normal, i.e. that normal is the cylinder's own axis).

The cylinder (of radius) is centered distance_from_end in from the timber's actual rounded_end face, offset laterally by lateral_offset (positive is toward rounded_end.rotate_about(rounded_face)). Only the material outside that cylinder is removed.

If distance_from_end is less than radius, the cylinder's surface passes beyond the actual end at the lateral center, so a flat band survives there and only the corners get rounded off (a filleted-corner rectangle) rather than a single continuous arc spanning the whole width -- a warning is raised in that case since it may not be the intended look.

Source code in kumiki/joints/workshop/decorative_joints.py

def cut_practice_rounded_end_decoration(
    timber: BlockLike,
    # so the round shape is visible on this face
    rounded_face: TimberFace,
    # and the round shape is cut towards this face
    rounded_end: TimberFace,
    radius: Numeric,
    distance_from_end: Numeric,
    lateral_offset: Numeric = 0
) -> Joint:
    """
    Rounds off `rounded_end` of `timber` with a single large-radius arc spanning
    the full width perpendicular to both `rounded_face` and `rounded_end` -- a
    gentle bowed/bullnose end profile, visible as a curved outline when looking
    straight at `rounded_face` (the arc's plane is perpendicular to
    `rounded_face`'s normal, i.e. that normal is the cylinder's own axis).

    The cylinder (of `radius`) is centered `distance_from_end` in from the
    timber's actual `rounded_end` face, offset laterally by `lateral_offset`
    (positive is toward `rounded_end.rotate_about(rounded_face)`). Only the
    material outside that cylinder is removed.

    If `distance_from_end` is less than `radius`, the cylinder's surface passes
    beyond the actual end at the lateral center, so a flat band survives there
    and only the corners get rounded off (a filleted-corner rectangle) rather
    than a single continuous arc spanning the whole width -- a warning is
    raised in that case since it may not be the intended look.
    """
    if safe_compare(distance_from_end, radius, Comparison.LT):
        warnings.warn(
            f"cut_practice_rounded_end_decoration: distance_from_end ({distance_from_end}) is less than "
            f"radius ({radius}) on {timber.ticket.path}'s {rounded_end.name} -- the lateral center will "
            f"stay flat/unrounded and only the corners will be filleted, rather than a single continuous "
            f"arc across the whole width.",
            stacklevel=2,
        )

    # The face perpendicular to both given faces -- the axis the arc spans
    # across (e.g. the board's width, for rounded_face=FRONT/rounded_end=TOP).
    span_face = rounded_end.rotate_about(rounded_face)

    axis_dir = timber.get_face_direction_global(rounded_face)
    end_dir = timber.get_face_direction_global(rounded_end)
    span_dir = timber.get_face_direction_global(span_face)

    half_span_reach = _available_extent_in_face_normal_axis(timber, span_face)
    assert safe_compare(radius - (half_span_reach + Abs(lateral_offset)), 0, Comparison.GE), (
        f"radius {radius} is too small to span {rounded_end.name}'s full width from a lateral offset of "
        f"{lateral_offset} (needs at least {half_span_reach + Abs(lateral_offset)})"
    )

    # Point on the actual end face, at the given lateral offset -- the local
    # origin (start_distance=0 equivalent) for both the prism and the cylinder.
    end_reference = get_center_point_on_face_global(rounded_end, timber) + span_dir * lateral_offset
    cylinder_center = end_reference - end_dir * distance_from_end

    cylinder = Cylinder(
        axis_direction=axis_dir,
        radius=radius,
        position=cylinder_center,
        start_distance=-timber.get_half_rough_size_in_face_normal_axis(rounded_face.get_opposite_face()),
        end_distance=timber.get_half_rough_size_in_face_normal_axis(rounded_face),
        label=CutCSGLabel("rounded_end_arc"),
    )

    # A generously-oversized prism covering the corner region -- from exactly
    # the cylinder's center distance back to the actual end (tight, since that
    # fully brackets where the cylinder's surface can be, given the assertion
    # above), and comfortably wider than the cross-section in every other
    # direction (harmless -- nothing exists there to over-cut).
    prism_orientation = Orientation(Matrix([
        [span_dir[0], axis_dir[0], end_dir[0]],
        [span_dir[1], axis_dir[1], end_dir[1]],
        [span_dir[2], axis_dir[2], end_dir[2]],
    ]))
    prism_span_size = scalar(2) * (half_span_reach + Abs(lateral_offset) + radius)
    prism_axis_size = (
        timber.get_half_rough_size_in_face_normal_axis(rounded_face)
        + timber.get_half_rough_size_in_face_normal_axis(rounded_face.get_opposite_face())
    )
    prism = RectangularPrism(
        size=Matrix([prism_span_size, prism_axis_size]),
        transform=Transform(position=end_reference, orientation=prism_orientation),
        start_distance=-distance_from_end,
        end_distance=radius,
        label=CutCSGLabel("rounded_end_waste"),
    )

    negative_csg = adopt_csg(
        None,
        timber.transform,
        Difference(base=prism, subtract=[cylinder], label=CutCSGLabel("rounded_end_decoration")),
    )
    cutting = Cutting(
        timber=timber,
        negative_csg=negative_csg,
        label=CutCSGLabel("rounded_end_decoration"),
    )
    return Joint(
        cuttings={timber.ticket.path: cutting},
        ticket=JointTicket(joint_type="rounded_end_decoration"),
    )

cut_practice_rafter_tail_scallop_corner_end_decoration

cut_practice_rafter_tail_scallop_corner_end_decoration(timber: BlockLike, short_edge: Union[TimberShortEdge], scallop_height: Numeric, scallop_length: Numeric) -> Joint

---

           |

__◜ ←scallop_height ↑ scallop_width

cuts out a "scallop" shape from cut_side from scallop_height measured up from cut_side on the end_side to scallop_width (scallop_length) measured inwards from the end on the cut_side the scallop is the circle touching the 2 points above such that the circle is perpendicular with the end_side face.

The circle crosses the end_side face AT A right angle at the point scallop_height above cut_side (its tangent line there runs straight through end_side, along its own normal -- so the circle's center lies exactly ON the end_side plane), and simply passes through the point scallop_length in from the end along cut_side (so there is a slight kink there, where the curve meets the flat run of cut_side).

Parameters:

Name	Type	Description	Default
timber	BlockLike	Timber to cut decoration on	required
short_edge	Union[TimberShortEdge]	The short edge defining the end face and cut face	required
scallop_height	Numeric	Height of scallop measured from cut_side on end_side	required
scallop_length	Numeric	Length of scallop measured inwards from end on cut_side	required

Returns:

Type	Description
Joint	Joint containing decorative cutting

Source code in kumiki/joints/workshop/decorative_joints.py

def cut_practice_rafter_tail_scallop_corner_end_decoration(
    timber: BlockLike,
    short_edge: Union[TimberShortEdge],
    scallop_height: Numeric,
    scallop_length: Numeric,
) -> Joint:
    """

    _______________
                   |
    ______________◜  ←scallop_height
                ↑
                scallop_width


    cuts out a "scallop" shape from cut_side from scallop_height measured up from cut_side on the end_side
    to scallop_width (scallop_length) measured inwards from the end on the cut_side
    the scallop is the circle touching the 2 points above such that the circle is perpendicular with the end_side face.

    The circle crosses the end_side face AT A right angle at the point
    scallop_height above cut_side (its tangent line there runs straight
    through end_side, along its own normal -- so the circle's center lies
    exactly ON the end_side plane), and simply passes through the point
    scallop_length in from the end along cut_side (so there is a slight kink
    there, where the curve meets the flat run of cut_side).

    Args:
        timber: Timber to cut decoration on
        short_edge: The short edge defining the end face and cut face
        scallop_height: Height of scallop measured from cut_side on end_side
        scallop_length: Length of scallop measured inwards from end on cut_side

    Returns:
        Joint containing decorative cutting
    """

    assert safe_compare(scallop_length, 0, Comparison.GT), "scallop_length must be positive"
    assert safe_compare(scallop_height, 0, Comparison.GT), "scallop_height must be positive"

    end_side = short_edge.end
    cut_side = short_edge.long_face

    end_face = end_side.to.face()
    cut_face = cut_side.to.face()

    # Marking space: origin is where the relevant centerplane meets both
    # cut_side and end_side (the midpoint of the edge they share). +x points
    # out through end_side, +y points away from cut_side (back into the timber).
    end_direction = timber.get_face_direction_global(end_face)
    cut_direction = timber.get_face_direction_global(cut_face)
    origin = (
        get_center_point_on_face_global(end_face, timber)
        + cut_direction * (timber.get_size_in_face_normal_axis(cut_face) / scalar(2))
    )

    # Point A: scallop_height up from cut_side, on end_side (local x=0).
    # Point B: scallop_length in from the end, on cut_side (local y=0).
    # Circle through A and B, perpendicular to end_side (i.e. to the local
    # y-axis) at A -- so its center shares A's local x=0 (lies exactly on the
    # end_side plane), offset from A only along local y by the radius.
    radius = (scallop_length * scallop_length + scallop_height * scallop_height) / (scalar(2) * scallop_height)
    center = origin - cut_direction * (scallop_height - radius)

    # The cylinder's axis is the cross-sectional axis perpendicular to both
    # cut_side and the length axis (rotating cut_side 90 degrees about
    # end_side's own axis lands on it); it extrudes across the timber's full
    # actual (rough) width on that axis so the scallop reaches both sides.
    perp_face = cut_face.rotate_about(end_face)
    perp_face_opposite = perp_face.get_opposite_face()
    cylinder = Cylinder(
        axis_direction=timber.get_face_direction_global(perp_face),
        radius=radius,
        position=center,
        start_distance=-timber.get_half_rough_size_in_face_normal_axis(perp_face_opposite),
        end_distance=timber.get_half_rough_size_in_face_normal_axis(perp_face),
        label=CutCSGLabel("scallop_arc"),
    )

    negative_csg = adopt_csg(None, timber.transform, cylinder)
    cutting = Cutting(
        timber=timber,
        negative_csg=negative_csg,
        label=CutCSGLabel("rafter_tail_scallop_decoration"),
    )
    return Joint(
        cuttings={timber.ticket.path: cutting},
        ticket=JointTicket(joint_type="rafter_tail_scallop_decoration"),
    )

cut_practice_path_extrusion_corner_end_decoration

cut_practice_path_extrusion_corner_end_decoration(timber: BlockLike, cut_corner: TimberShortEdge, cut_path: List[PathSegment]) -> Joint

path coordinates is based on cut_corner

+y | |_ |_|__ +x ^ cut_corner

generally speaking, path coordiantes is a line representing what you want to cut drown from the left end of the timber to the bottom face of the timber (based on the picture above)

specifically to form the cut out: - the 0'th path coordinate is extended to the end of the timber (x = 0) - that point is extended vertically to the rough face in the -y direction (relative to the diagram above) - then that point is extended to horizontally to the x coordinate of the last path coordinate - finally it is connected to the last path coordinate, and from there back to the 0'th path coordinate, closing the loop

The enclosed region (cut_path on the inside, the end/rough-face corner on the outside) is extruded across the timber's full actual (rough) width perpendicular to both cut_corner's end face and long face, and removed -- the same "extrude a 2D cut profile across the full perpendicular width" idea as cut_practice_rafter_tail_scallop_corner_end_decoration, just with an arbitrary line/arc path instead of a single circular arc.

Parameters:

Name	Type	Description	Default
timber	BlockLike	Timber to cut the decoration on	required
cut_corner	TimberShortEdge	the corner that is to be cut out, which determines the coordinates of the path based on the diagram above	required
cut_path	List[PathSegment]	the path, which must be drawn from the left edge to the bottom edge based on the diagram above.	required

Source code in kumiki/joints/workshop/decorative_joints.py

def cut_practice_path_extrusion_corner_end_decoration(
    timber: BlockLike,
    cut_corner: TimberShortEdge,
    cut_path: List[PathSegment],
) -> Joint:
    """
    path coordinates is based on cut_corner

    +y
    |
    |________
    |________|__ +x
    ^
    cut_corner

    generally speaking, path coordiantes is a line representing what you want to cut drown from the left end of the timber to the bottom face of the timber (based on the picture above)

    specifically to form the cut out:
    - the 0'th path coordinate is extended to the end of the timber (x = 0)
    - that point is extended vertically to the rough face in the -y direction (relative to the diagram above)
    - then that point is extended to horizontally to the x coordinate of the last path coordinate
    - finally it is connected to the last path coordinate, and from there back to
      the 0'th path coordinate, closing the loop

    The enclosed region (cut_path on the inside, the end/rough-face corner on
    the outside) is extruded across the timber's full actual (rough) width
    perpendicular to both cut_corner's end face and long face, and removed --
    the same "extrude a 2D cut profile across the full perpendicular width"
    idea as cut_practice_rafter_tail_scallop_corner_end_decoration, just with
    an arbitrary line/arc path instead of a single circular arc.

    Arguments:
        timber: Timber to cut the decoration on
        cut_corner: the corner that is to be cut out, which determines the coordinates of the  path based on the diagram above
        cut_path: the path, which must be drawn from the left edge to the bottom edge based on the diagram above.
    """
    assert len(cut_path) > 0, "cut_path must have at least one segment"

    end_side = cut_corner.end
    cut_side = cut_corner.long_face
    end_face = end_side.to.face()
    cut_face = cut_side.to.face()

    # Marking space: origin is where the relevant centerplane meets both
    # cut_side and end_side (the midpoint of the edge they share) -- same
    # frame cut_practice_rafter_tail_scallop_corner_end_decoration uses.
    # Local +x points from the end INTO the timber (so x=0, per the diagram,
    # is the end face itself); local +y points from cut_side INTO the timber
    # (so -y, per the diagram, is outward past cut_side's perfect face --
    # where any rough-stock excess lives).
    end_direction = timber.get_face_direction_global(end_face)
    cut_direction = timber.get_face_direction_global(cut_face)
    origin = (
        get_center_point_on_face_global(end_face, timber)
        + cut_direction * (timber.get_size_in_face_normal_axis(cut_face) / scalar(2))
    )
    local_x_dir = -end_direction
    local_y_dir = -cut_direction

    # The axis perpendicular to both end_side and cut_side -- the extrusion
    # runs along this, across the timber's full rough width, same as the
    # scallop's cylinder axis.
    perp_face = cut_face.rotate_about(end_face)
    perp_face_opposite = perp_face.get_opposite_face()
    extrusion_dir = timber.get_face_direction_global(perp_face)

    orientation = Orientation(Matrix([
        [local_x_dir[0], local_y_dir[0], extrusion_dir[0]],
        [local_x_dir[1], local_y_dir[1], extrusion_dir[1]],
        [local_x_dir[2], local_y_dir[2], extrusion_dir[2]],
    ]))

    path_start = cut_path[0].start
    path_end = cut_path[-1].end
    y_rough = -_rough_excess_in_face_normal_axis(timber, cut_face)

    loop_start = create_v2(scalar(0), path_start[1])
    rough_near_end = create_v2(scalar(0), y_rough)
    rough_near_path_end = create_v2(path_end[0], y_rough)

    segments: List[PathSegment] = []
    start_connector = _line_if_nondegenerate(loop_start, path_start)
    if start_connector is not None:
        segments.append(start_connector)
    segments.extend(cut_path)
    for a, b in ((path_end, rough_near_path_end), (rough_near_path_end, rough_near_end), (rough_near_end, loop_start)):
        closing_segment = _line_if_nondegenerate(a, b)
        if closing_segment is not None:
            segments.append(closing_segment)

    loop = Path(segments)
    # cut_path is drawn "downhill" (end toward the end face, bottom toward
    # cut_side) per the diagram, which makes the loop as constructed above
    # come out clockwise -- flip it so is_valid()'s CCW requirement (needed
    # for correct outward normals) is satisfied regardless.
    if safe_compare(loop.signed_area(), 0, Comparison.LT):
        loop = loop.reversed()
    assert loop.is_valid(), (
        f"cut_practice_path_extrusion_corner_end_decoration: constructed cut path for "
        f"{cut_corner.name} is not a valid simple loop -- check cut_path connectivity"
    )

    extrusion = PathExtrusion(
        path=loop,
        transform=Transform(position=origin, orientation=orientation),
        start_distance=-timber.get_half_rough_size_in_face_normal_axis(perp_face_opposite),
        end_distance=timber.get_half_rough_size_in_face_normal_axis(perp_face),
        label=CutCSGLabel("path_extrusion_decoration"),
    )

    negative_csg = adopt_csg(None, timber.transform, extrusion)
    cutting = Cutting(
        timber=timber,
        negative_csg=negative_csg,
        label=CutCSGLabel("path_extrusion_corner_end_decoration"),
    )
    return Joint(
        cuttings={timber.ticket.path: cutting},
        ticket=JointTicket(joint_type="path_extrusion_corner_end_decoration"),
    )

cut_practice_straight_angled_end_cut_decoration

cut_practice_straight_angled_end_cut_decoration(timber: BlockLike, front_face: TimberFace, position_from_end: Numeric, angle: Numeric = degrees(0), angle_towards_face: Optional[TimberFace] = None) -> Joint

---

front_face \ <-timber_end _______\

Parameters:

Name	Type	Description	Default
timber	BlockLike	the timber to have the decoration cut on it	required
timber_end		the end of the timber the decoration is cut on	required
position_from_end	Numeric	distance from timber_end along the timber's centerline where the angle cut plane lies	required
angle	Numeric	angle to make the cut, 0 is perpendicular, angle is in the front_face axis	degrees(0)
front_face	TimberFace	the face that the angle cut is visible from	required

Source code in kumiki/joints/workshop/decorative_joints.py

def cut_practice_straight_angled_end_cut_decoration(
        timber: BlockLike, 
        front_face: TimberFace, 
        position_from_end: Numeric,
        angle: Numeric = degrees(0),
        angle_towards_face: Optional[TimberFace] = None
    ) -> Joint:
    """

    ____________
    front_face  \\      <-timber_end
    _____________\\

    Args:
        timber: the timber to have the decoration cut on it
        timber_end: the end of the timber the decoration is cut on
        position_from_end: distance from timber_end along the timber's centerline where the angle cut plane lies 
        angle: angle to make the cut, 0 is perpendicular, angle is in the front_face axis
        front_face: the face that the angle cut is visible from
    """
    # TODO finish
    pass