Skip to content

3D modeling in Python, built for LLMs.

20.6 KB
Raw Blame
"""Joints: declaring them, the kinematic tree, copies, transforms and mirrors,
and every error a joint can raise at declaration."""
import math
import unittest

import bpy  # noqa: F401

import sand3d as s3d
from sand3d import _core
from sand3d.joints import axis_in_world, joints_of, parent_of


def close(test, a, b, places=6):
    test.assertEqual(len(a), len(b))
    for x, y in zip(a, b):
        test.assertAlmostEqual(x, y, places=places)


def washer():
    """A cabinet with a door on the -Y edge of its +X face."""
    cab = s3d.box("cab", 600, 600, 850)
    door = s3d.at(s3d.box("door", 20, 560, 800), x=310, z=25)
    return cab, door


class Declaring(unittest.TestCase):

    def setUp(self):
        s3d.empty_scene()
        self.cab, self.door = washer()

    def test_a_joint_returns_its_child_and_neither_moves_nor_reparents_it(self):
        before = _core.world(self.door)
        got = s3d.joint("door_hinge", self.door, s3d.bbox(self.cab, "+X-Y"), axis="-Z", range=(0, 143))
        self.assertIs(got, self.door)
        self.assertEqual(_core.world(self.door), before)
        self.assertIsNone(self.door.parent)
        self.assertIs(parent_of(self.door), self.cab)
        j, = joints_of(self.door)
        self.assertEqual((j["name"], j["kind"], j["range"], j["value"]), ("door_hinge", "revolute", [0.0, 143.0], 0))
        origin, axis = axis_in_world(self.door, 0)
        close(self, origin, (300, -300, 425))
        close(self, axis, (0, 0, -1))

    def test_the_axis_is_a_direction_of_the_parent_s_space_or_the_frame_s_normal(self):
        knob = s3d.at(s3d.cylinder("knob", 40, 10), on=self.cab.face("+X").move(x=200, y=700))
        s3d.joint("dial", knob, self.cab.face("+X"), kind="continuous")
        close(self, axis_in_world(knob, 0)[1], (1, 0, 0))                # "normal": the face's Z
        unit = s3d.transform(s3d.group("unit", self.cab, self.door, knob), rz=90)
        s3d.joint("hinge", self.door, s3d.bbox(self.cab, "+X-Y"), axis="-Z", range=(0, 90))
        close(self, axis_in_world(self.door, 0)[1], (0, 0, -1))         # in the unit's space: Z stays Z
        drawer = s3d.at(s3d.box("drawer", 100, 300, 50), x=200, z=700)
        unit2 = s3d.transform(s3d.group("unit2", s3d.copy(self.cab), drawer), rx=90)
        s3d.joint("slide", drawer, s3d.bbox(unit2.children[0], "+X"), kind="prismatic", axis="+X", range=(0, 200))
        close(self, axis_in_world(drawer, 0)[1], (1, 0, 0))
        self.assertIsNotNone(unit)

    def test_a_group_or_an_assembly_is_a_part(self):
        handle = s3d.at(s3d.box("handle", 30, 20, 120), x=330, y=200, z=425)
        leaf = s3d.group("leaf", self.door, handle)
        s3d.joint("hinge", leaf, s3d.bbox(self.cab, "+X-Y"), axis="-Z", range=(0, 90))
        self.assertEqual(joints_of(leaf)[0]["name"], "hinge")
        arm = s3d.assembly("arm", s3d.box("body", 10, 10, 100), tip=s3d.Frame((0, 0, 100)))
        got = s3d.joint("shoulder", arm, self.cab.face("top"), axis="+X", range=(-45, 45))
        self.assertIs(got, arm)
        lamp = s3d.at(s3d.box("lamp", 20, 20, 20), z=950)
        s3d.joint("elbow", lamp, arm.tip, axis="+Y", range=(-90, 90))   # an assembly's anchor is read on it
        self.assertIs(parent_of(lamp), arm.root)

    def test_joints_may_come_after_the_group(self):
        machine = s3d.assembly("machine", self.cab, self.door)
        s3d.joint("hinge", self.door, s3d.bbox(self.cab, "+X-Y"), axis="-Z", range=(0, 90))
        self.assertIs(self.door.parent, machine.root)
        close(self, axis_in_world(self.door, 0)[0], (300, -300, 425))

    def test_two_joints_on_one_child_hang_on_one_parent(self):
        cap = s3d.at(s3d.cylinder("cap", 30, 20), z=850)
        top = self.cab.face("top")
        s3d.joint("turn", cap, top, kind="revolute", range=(0, 720))
        s3d.joint("lift", cap, top, kind="prismatic", follows="turn", ratio=3 / 360)
        self.assertEqual([j["name"] for j in joints_of(cap)], ["turn", "lift"])
        self.assertEqual(joints_of(cap)[1]["follows"], 0)
        with self.assertRaisesRegex(ValueError, r"^joint 'tilt': 'cap' already hangs on 'cab' by 'turn': every joint "
                                                r"of one child is read on the same parent$"):
            s3d.joint("tilt", cap, self.door.face("+X"), range=(0, 1))

    def test_the_frame_stays_on_its_part(self):
        hinge = s3d.bbox(self.cab, "+X-Y")
        s3d.transform([self.cab, self.door], x=1000)        # read, then moved: the pivot is where the part is
        s3d.joint("hinge", self.door, hinge, axis="-Z", range=(0, 90))
        close(self, axis_in_world(self.door, 0)[0], (1300, -300, 425))


class CopiesAndMirrors(unittest.TestCase):

    def setUp(self):
        s3d.empty_scene()
        self.cab, self.door = washer()
        s3d.joint("hinge", self.door, s3d.bbox(self.cab, "+X-Y"), axis="-Z", range=(0, 143))

    def test_a_copy_carries_its_joints_and_hangs_on_the_same_parent(self):
        twin = s3d.copy(self.door)
        self.assertEqual(joints_of(twin), joints_of(self.door))
        self.assertIs(parent_of(twin), self.cab)

    def test_a_copy_of_the_whole_hangs_on_the_copy_of_its_parent(self):
        machine = s3d.group("machine", self.cab, self.door)
        twin = s3d.copy(machine)
        door2 = next(c for c in twin.children if c.get("s3d_name") == "door")
        cab2 = next(c for c in twin.children if c.get("s3d_name") == "cab")
        self.assertIs(parent_of(door2), cab2)
        self.assertIs(parent_of(self.door), self.cab)
        copies = s3d.at(machine, on=s3d.grid(2, 1, 2000))
        for copy in copies:
            door = next(c for c in copy.children if c.get("s3d_name") == "door")
            self.assertIs(parent_of(door).parent, copy)

    def test_transform_moves_a_jointed_part_with_its_pivot(self):
        s3d.transform(self.door, x=50)
        close(self, axis_in_world(self.door, 0)[0], (350, -300, 425))
        from sand3d.joints import rest_basis
        self.assertEqual(rest_basis(self.door).translation.x, 360.0)

    def test_a_mirror_image_moves_as_the_image_of_the_motion(self):
        twin = s3d.transform(s3d.copy(self.door), mirror="y")
        origin, axis = axis_in_world(twin, 0)
        close(self, origin, (300, 300, 425))
        close(self, axis, (0, 0, 1))                       # −M·u: the revolute axis turns over
        self.assertEqual(joints_of(twin)[0]["range"], [0.0, 143.0])
        drawer = s3d.at(s3d.box("drawer", 100, 300, 50), x=-200, z=700)
        s3d.joint("slide", drawer, s3d.bbox(self.cab, "-X"), kind="prismatic", axis="-X", range=(0, 200))
        image = s3d.transform(s3d.copy(drawer), mirror="x")
        close(self, axis_in_world(image, 0)[1], (1, 0, 0))   # M·u: a slide's image slides the image way


class Errors(unittest.TestCase):

    def setUp(self):
        s3d.empty_scene()
        self.cab, self.door = washer()
        self.edge = s3d.bbox(self.cab, "+X-Y")

    def raises(self, message, error=ValueError, **kwargs):
        args = dict(name="j", child=self.door, on=self.edge, axis="-Z", range=(0, 90))
        args.update(kwargs)
        if args["axis"] is None:
            del args["axis"]
        with self.assertRaises(error) as caught:
            s3d.joint(**args)
        self.assertEqual(str(caught.exception), message)
        self.assertEqual(joints_of(self.door), [])

    def test_an_unknown_kind_or_axis(self):
        self.raises("joint 'j': kind 'hinge' is none of revolute, continuous, prismatic, free", kind="hinge")
        self.raises("joint 'j': axis 'Z+' is none of \"+X\" \"-X\" \"+Y\" \"-Y\" \"+Z\" \"-Z\" — a direction in the "
                    "space the parent lives in — or \"normal\", the Z of the frame `on`", axis="Z+")
        self.raises("joint 'j': axis (0, 0, 1) is none of \"+X\" \"-X\" \"+Y\" \"-Y\" \"+Z\" \"-Z\" — a direction in "
                    "the space the parent lives in — or \"normal\", the Z of the frame `on`", axis=(0, 0, 1))

    def test_a_range_missing_or_given_where_it_has_no_place(self):
        self.raises("joint 'j': a revolute joint needs range=(low, high), in degrees — kind=\"continuous\" turns "
                    "without end", range=None)
        self.raises("joint 'j': a prismatic joint needs range=(low, high), in the program's unit", kind="prismatic",
                    range=None)
        self.raises("joint 'j': a continuous joint turns without end: it takes no range", kind="continuous")
        self.raises("joint 'j': a free joint moves freely: it takes no range", kind="free", axis=None)
        s3d.joint("lead", s3d.at(s3d.box("k", 5, 5, 5), z=860), self.cab.face("top"), kind="continuous")
        self.raises("joint 'j': a joint that follows another takes no range: its range is the other's × ratio",
                    follows="lead")

    def test_a_range_without_zero_or_empty(self):
        self.raises("joint 'j': range (10, 90) does not contain 0: everything is built at rest, every joint at 0 — "
                    "build the part where it rests, and give the range from there", range=(10, 90))
        self.raises("joint 'j': range (90, 0) is empty: low comes before high", range=(90, 0))
        self.raises("joint 'j': range is (low, high), two numbers, not 90", TypeError, range=90)

    def test_an_axis_given_to_a_free_joint(self):
        self.raises("joint 'j': a free joint moves every way: it takes no axis", kind="free", range=None)
        self.raises("joint 'j': a free joint moves every way: it takes no axis", kind="free", range=None,
                    axis="normal")
        plug = s3d.at(s3d.box("plug", 10, 10, 10), x=400)
        s3d.joint("cord", plug, self.cab.face("+X"), kind="free")       # no axis written: none taken
        self.assertIsNone(joints_of(plug)[0]["axis"])

    def test_on_not_read_on_a_part_or_read_on_the_child(self):
        self.raises("joint 'j': on is a frame built by hand, read on no part: read it on the part the child moves on "
                    "— ob.face(...), s3d.bbox(ob, \"+X-Y\"), an assembly's anchor — so that the joint knows its parent",
                    on=s3d.Frame((300, -300, 425)))
        self.raises("joint 'j': on is a frame read on the parent part — ob.face(...), s3d.bbox(ob, ...), an "
                    "assembly's anchor — not tuple", TypeError, on=(300, -300, 425))
        self.raises("joint 'j': on is read on the child itself: read it on the part 'door' moves on",
                    on=self.door.face("+X"))
        knob = s3d.at(s3d.box("knob", 10, 10, 10), x=325)
        leaf = s3d.group("leaf", self.door, knob)
        with self.assertRaisesRegex(ValueError, r"^joint 'j': on is read on 'knob', which is inside the child: read it "
                                                r"on the part 'leaf' moves on$"):
            s3d.joint("j", leaf, knob.face("+X"), range=(0, 1))

    def test_a_cycle_in_the_tree(self):
        s3d.joint("hinge", self.door, self.edge, axis="-Z", range=(0, 90))
        with self.assertRaisesRegex(ValueError, r"^joint 'back': 'door' already hangs on 'cab', through the joints "
                                                r"declared: hanging 'cab' on it makes a cycle$"):
            s3d.joint("back", self.cab, self.door.face("+X"), range=(0, 1))
        knob = s3d.at(s3d.box("knob", 10, 10, 10), x=325, z=500)
        s3d.joint("turn", knob, self.door.face("+X"), kind="continuous")
        with self.assertRaisesRegex(ValueError, r"^joint 'loop': 'knob' already hangs on 'cab'"):
            s3d.joint("loop", self.cab, knob.face("+X"), range=(0, 1))

    def test_the_name_child_and_ratio(self):
        with self.assertRaisesRegex(TypeError, r"^joint: name is the joint's name, a string, not 3$"):
            s3d.joint(3, self.door, self.edge, range=(0, 1))
        with self.assertRaisesRegex(TypeError, r"^joint 'j': child is the part that moves — a solid, a group or an "
                                               r"assembly — not Frame$"):
            s3d.joint("j", self.edge, self.edge, range=(0, 1))
        s3d.joint("lead", s3d.at(s3d.box("k", 5, 5, 5), z=860), self.cab.face("top"), kind="continuous")
        self.raises("joint 'j': ratio is a number other than 0 — the follower's value per unit of the followed "
                    "joint's — not 0", range=None, follows="lead", ratio=0)


class Follows(unittest.TestCase):

    def setUp(self):
        s3d.empty_scene()
        self.base = s3d.box("base", 200, 100, 10)
        self.big = s3d.at(s3d.cylinder("big", 60, 10), x=-40, z=10)
        self.small = s3d.at(s3d.cylinder("small", 20, 10), x=0, z=10)
        s3d.joint("drive", self.big, self.base.face("top").move(-40), kind="continuous")

    def test_follows_a_child_or_a_joint_name(self):
        s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows=self.big, ratio=-3)
        self.assertEqual(joints_of(self.small)[0]["ratio"], -3.0)
        self.assertIs(self.small["s3d~follows.0"], self.big)
        third = s3d.at(s3d.cylinder("third", 10, 10), x=30, z=10)
        s3d.joint("idler", third, self.base.face("top").move(30), kind="continuous", follows="gear")
        self.assertIs(third["s3d~follows.0"], self.small)

    def test_an_ambiguous_name_a_cycle_a_free_leader(self):
        s3d.copy(self.big)
        with self.assertRaisesRegex(ValueError, r"^joint 'gear': follows 'drive', which names 2 joints \(on 'big': "
                                                r"copies carry their joints\): give the part it moves, follows=part$"):
            s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows="drive")
        with self.assertRaisesRegex(ValueError, r"^joint 'gear': follows 'nope', and no joint has that name$"):
            s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows="nope")
        with self.assertRaisesRegex(ValueError, r"^joint 'gear': follows its own child, which has no joint yet: a "
                                                r"joint cannot follow itself \(a cycle\)$"):
            s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows=self.small)
        with self.assertRaisesRegex(ValueError, r"^joint 'gear': follows 'base', which has no joint$"):
            s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows=self.base)
        loose = s3d.at(s3d.box("loose", 5, 5, 5), x=90, z=10)
        s3d.joint("float", loose, self.base.face("top"), kind="free")
        with self.assertRaisesRegex(ValueError, r"^joint 'gear': follows 'float', a free joint: it has no value to "
                                                r"follow$"):
            s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows="float")
        with self.assertRaisesRegex(ValueError, r"^joint 'f': a free joint follows nothing: it has no value$"):
            s3d.joint("f", self.small, self.base.face("top"), kind="free", follows="float")

    def test_two_joints_followed_by_their_child_need_the_name(self):
        s3d.joint("lift", self.big, self.base.face("top").move(-40), kind="prismatic", axis="+Z", range=(0, 5))
        with self.assertRaisesRegex(ValueError, r"^joint 'gear': follows 'big', which has 2 joints \('drive', 'lift'\): "
                                                r"name the one, follows=\"drive\"$"):
            s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows=self.big)


    def test_a_slide_that_follows_an_endless_turn(self):
        rack = s3d.at(s3d.box("rack", 100, 10, 10), y=40, z=10)
        message = (r"^joint 'slide': a slide that follows '{}', which turns without end, would slide without end: "
                   r"give '{}' a range$")
        with self.assertRaisesRegex(ValueError, message.format("drive", "drive")):
            s3d.joint("slide", rack, self.base.face("top"), kind="prismatic", axis="+X", follows=self.big, ratio=0.5)
        s3d.joint("gear", self.small, self.base.face("top"), kind="continuous", follows=self.big, ratio=-3)
        with self.assertRaisesRegex(ValueError, message.format("gear", "gear")):           # down a chain of follows
            s3d.joint("slide", rack, self.base.face("top"), kind="prismatic", axis="+X", follows="gear")
        self.assertEqual(joints_of(rack), [])


class PlacedOn(unittest.TestCase):
    """A child placed on a frame read on its parent must still sit where that frame put
    it: its pivot follows the parent, and it would not."""

    def setUp(self):
        s3d.empty_scene()
        self.cab = s3d.box("cab", 200, 200, 200)
        self.top = self.cab.face("+Z")
        self.knob = s3d.box("knob", 80, 20, 20)

    def refused(self):
        with self.assertRaisesRegex(ValueError, r"^joint 'dial': 'knob' is no longer where its frame put it on 'cab' "
                                                r"— 'cab' moved after the frame was read, or after 'knob' was placed: "
                                                r"its pivot would follow 'cab' and 'knob' would not\. Group them so "
                                                r"they move together, or read the frame on 'cab' where it is now$"):
            s3d.joint("dial", self.knob, self.top, kind="continuous")
        self.assertEqual(joints_of(self.knob), [])

    def test_the_parent_moved_before_the_child_was_placed(self):
        s3d.at(self.cab, x=300)
        s3d.at(self.knob, on=self.top)
        self.refused()

    def test_the_parent_moved_after_the_child_was_placed(self):
        s3d.at(self.knob, on=self.top)
        s3d.transform(self.cab, x=300)
        self.refused()

    def test_moved_together_or_placed_again(self):
        s3d.at(self.knob, on=self.top)
        s3d.at(s3d.group("g", self.cab, self.knob), x=300)                  # together: still on it
        s3d.joint("dial", self.knob, self.top, kind="continuous")
        close(self, axis_in_world(self.knob, 0)[0], (300, 0, 200))
        s3d.empty_scene()
        cab = s3d.box("cab", 200, 100, 20)
        keys = s3d.at(s3d.box("key", 10, 10, 5), on=s3d.grid(3, 2, 30, 30, on=cab.face("+Z")))
        s3d.transform(s3d.group("keys", keys), z=1)                         # the child moved on purpose
        for k in keys:
            s3d.joint("press", k, cab.face("+Z"), kind="prismatic", axis="-Z", range=(0, 4))


class OtherVerbs(unittest.TestCase):

    def setUp(self):
        s3d.empty_scene()
        self.cab, self.door = washer()
        s3d.joint("hinge", self.door, s3d.bbox(self.cab, "+X-Y"), axis="-Z", range=(0, 143))

    def test_at_refuses_a_jointed_part(self):
        message = ("at: 'door' moves by its joint 'hinge': placing it would tear it off its pivot — place it before "
                   "the joint, or s3d.transform it, which moves it with its pivot")
        for call in (lambda: s3d.at(self.door, x=1), lambda: s3d.at(self.door, on=s3d.grid(2, 1, 10)),
                     lambda: s3d.at([self.door], z=3)):
            with self.assertRaises(ValueError) as caught:
                call()
            self.assertEqual(str(caught.exception), message)
        s3d.at(self.door)                                   # nothing to change: nothing refused
        machine = s3d.group("machine", self.cab, self.door)
        s3d.at(machine, x=100)                              # its group moves whole

    def test_join_and_cut_refuse_to_use_up_a_jointed_part_or_its_parent(self):
        other = s3d.box("other", 10, 10, 10)
        for verb in ("join", "cut", "intersect", "merge"):
            with self.subTest(verb=verb):
                call = (lambda: getattr(s3d, verb)(other, self.door)) if verb != "merge" else \
                    (lambda: s3d.merge(other, self.door))
                with self.assertRaises(ValueError) as caught:
                    call()
                self.assertEqual(str(caught.exception),
                                 f"{verb}: 'door' moves by its joint 'hinge': {verb} would use it up, and the joint with "
                                 f"it (a copy carries its joints too) — make the tool from a part that does not move; "
                                 f"s3d.seat(host, part) cuts the cavity and leaves the part as it is")
        with self.assertRaisesRegex(ValueError, r"^join: 'door' hangs on 'cab' by 'hinge': join would use 'cab' up, "
                                                r"and leave the joint on nothing$"):
            s3d.join(other, self.cab)
        s3d.cut(self.door, s3d.at(s3d.cylinder("peephole", 10, 40), x=310, z=500, ry=90))   # the jointed part stays
        with self.assertRaisesRegex(ValueError, r"^join: 'door' moves by its joint 'hinge'"):
            s3d.join(self.cab, s3d.copy(self.door))

    def test_the_digest_holds_the_joint(self):
        from harness import _object_digest
        before = _object_digest(self.door)
        self.door["s3d~joints"] = self.door["s3d~joints"].replace("143.0", "140.0")
        self.assertNotEqual(_object_digest(self.door), before)


if __name__ == "__main__":
    unittest.main()