Documentation tweaks and re-adding dropFrame (#192)

* Add endianness to docs. Closes #181

* Clarification in transform docs. Closes #183

* Add segment note to docs. Closes #185

* Re-add dropFrame as an optional field in timecode. Closes #188

---------

Co-authored-by: [email protected] <[email protected]>

Author: jamesmosys

src/main/python/camdkit/clip.py

@@ -128,8 +128,10 @@ class Clip(CompatibleBaseModel):
                                "constraints": TRANSFORMS,
                                "uniqueItems": False})] = None
     """A list of transforms.
-    Transforms are composed in order with the last in the list representing
-    the X,Y,Z in meters of camera sensor relative to stage origin.
+    Transforms are composed in sequential order, starting with the first
+    transform in the list and concluding with the last transform in the list.
+    The compound transform contains the position (in meters) and orientation
+    (in degrees) of the camera sensor relative to stage origin.
     The Z axis points upwards and the coordinate system is right-handed.
     Y points in the forward camera direction (when pan, tilt and roll are
     zero).

src/main/python/camdkit/examples.py

@@ -152,9 +152,9 @@ def _get_recommended_dynamic_clip():
   clip.tracker_notes = ("Example generated sample.",)
   # timing
   clip.timing_mode = (TimingMode.EXTERNAL,)
-  clip.timing_sample_rate = (Fraction(24000, 1001),)
+  clip.timing_sample_rate = (Fraction(24, 1),)
   clip.timing_timecode = (Timecode(hours=1,minutes=2,seconds=3,frames=4,
-                                   frame_rate=StrictlyPositiveRational(24000, 1001)),)
+                                   frame_rate=StrictlyPositiveRational(24, 1)),)
   # transforms
   v, r = _example_transform_components()
   clip.transforms = ((Transform(translation=v, rotation=r, id="Camera"),),)
@@ -213,6 +213,9 @@ def _get_complete_dynamic_clip():
       mean_path_delay=0.000123,
       vlan=100)
   ),)
+  clip.timing_timecode = (Timecode(hours=1,minutes=2,seconds=3,frames=4,
+                                   frame_rate=StrictlyPositiveRational(24000, 1001),
+                                   sub_frame=1,dropFrame=True),)
   #   transforms
   clip.global_stage = (GlobalPosition(100.0,200.0,300.0,100.0,200.0,300.0),)
   v = Vector3(x=1.0, y=2.0, z=3.0)

src/main/python/camdkit/mosys/f4.py

@@ -82,8 +82,9 @@ def to_timecode(self) -> Timecode:
      seconds = ((self.data_bits2 << 2) % 64) + ((self.data_bits3 >> 6) % 4)
      frames = self.data_bits3 % 64
      sub_frame = 0
+     dropFrame = False
      return Timecode(hours=hours,minutes=minutes,seconds=seconds,frames=frames,
-                     frame_rate=frame_rate,sub_frame=sub_frame)
+                     frame_rate=frame_rate,sub_frame=sub_frame,dropFrame=dropFrame)
 
 class F4Packet:
   command_byte: int = 0

src/main/python/camdkit/timing_types.py

@@ -78,6 +78,7 @@ class Timecode(CompatibleBaseModel):
     frames: int = Field(..., ge=0, le=119, strict=True)
     frame_rate: Annotated[StrictlyPositiveRational, Field(alias="frameRate")]
     sub_frame: Annotated[NonNegativeInt, Field(alias="subFrame", strict=True)] = 0
+    dropFrame: bool | None = False
 
     # noinspection PyNestedDecorators
     @field_validator("frame_rate", mode="before")

src/test/python/test_clip.py

@@ -297,10 +297,10 @@ def test_timing_regular_parameters(self):
         timing_sample_rate = (sample_rate, sample_rate)
         timecode0 = Timecode(hours=1, minutes=2, seconds=3,frames=4,
                             frame_rate=StrictlyPositiveRational(24, 1),
-                            sub_frame=0)
+                            sub_frame=0,dropFrame=False)
         timecode1= Timecode(hours=1, minutes=2, seconds=3, frames=5,
                             frame_rate=StrictlyPositiveRational(24, 1),
-                            sub_frame=1)
+                            sub_frame=1,dropFrame=True)
         timing_timecode = (timecode0, timecode1)
         ptp = SynchronizationPTP(profile=PTPProfile.SMPTE_2059_2_2021,
                                  domain=1,
@@ -355,10 +355,10 @@ def test_timing_regular_parameters(self):
             {"num": 24000, "denom": 1001}))
         self.assertTupleEqual(clip_as_json["timing"]["timecode"], (
             {"hours":1, "minutes":2, "seconds":3, "frames":4,
-             # no subFrame serialized because value was that of the default
+             # no subFrame / dropFrame serialized because values are the defaults
              "frameRate": {"num": 24, "denom": 1}},
             {"hours": 1,"minutes": 2,"seconds": 3,"frames": 5,
-             "frameRate": {"num": 24, "denom": 1}, "subFrame": 1}))
+             "frameRate": {"num": 24, "denom": 1}, "subFrame": 1, "dropFrame": True}))
         expected_synchronization_dict = {
             "locked": True,
             "source": "ptp",

src/test/python/test_model.py

@@ -86,10 +86,10 @@ def test_serialize(self):
     clip.timing_sample_rate = (Fraction(24000, 1001), Fraction(24000, 1001))
     clip.timing_timecode = (Timecode(hours=1, minutes=2, seconds=3, frames=4,
                                      frame_rate=StrictlyPositiveRational(24, 1),
-                                     sub_frame=0),
+                                     sub_frame=0,dropFrame=False),
                             Timecode(hours=1, minutes=2, seconds=3, frames=5,
                                      frame_rate=StrictlyPositiveRational(24, 1),
-                                     sub_frame=0))
+                                     sub_frame=0,dropFrame=False))
     sync = Synchronization(
       frequency=Fraction(24000, 1001),
       locked=True,
@@ -778,7 +778,7 @@ def test_timecode(self):
     with self.assertRaises(ValueError):
       Timecode(hours=0, minutes=0, seconds=0, frames=0,
                frame_rate=StrictlyPositiveRational(0,1),
-               sub_frame=0)
+               sub_frame=0,dropFrame=False)
     self.assertTrue(TimingTimecode.validate(Timecode(hours=0, minutes=0, seconds=0, frames=0,
                                                      frame_rate=StrictlyPositiveRational(24, 1))))
     self.assertTrue(TimingTimecode.validate(Timecode(hours=1, minutes=2, seconds=3, frames=4,
@@ -787,48 +787,49 @@ def test_timecode(self):
                                                      frame_rate=StrictlyPositiveRational(24, 1))))
     with self.assertRaises(ValueError):
         Timecode(hours=-1, seconds=2, minutes=3, frames=4,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=24, seconds=2, minutes=3, frames=4,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=-1, minutes=3, frames=4,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=60, minutes=3, frames=4,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=-1, frames=4,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=60, frames=4,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=-1,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=24,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=24,
-        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=1)
+        frame_rate=StrictlyPositiveRational(24, 1), sub_frame=1, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=25,
-        frame_rate=StrictlyPositiveRational(25, 1), sub_frame=1)
+        frame_rate=StrictlyPositiveRational(25, 1), sub_frame=1, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=30,
-        frame_rate=StrictlyPositiveRational(30, 1), sub_frame=1)
+        frame_rate=StrictlyPositiveRational(30, 1), sub_frame=1, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=30,
-        frame_rate=StrictlyPositiveRational(30, 1), sub_frame=1)
+        frame_rate=StrictlyPositiveRational(30, 1), sub_frame=1, dropFrame=False)
     self.assertTrue(TimingTimecode.validate(Timecode(hours=1, minutes=2, seconds=3, frames=119,
-                                                     frame_rate=StrictlyPositiveRational(120, 1), sub_frame=0)))
+                                                     frame_rate=StrictlyPositiveRational(120, 1),
+                                                     sub_frame=0, dropFrame=False)))
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=120,
-        frame_rate=StrictlyPositiveRational(120, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(120, 1), sub_frame=0, dropFrame=False)
     with self.assertRaises(ValueError):
         Timecode(hours=1, seconds=2, minutes=3, frames=120,
-        frame_rate=StrictlyPositiveRational(121, 1), sub_frame=0)
+        frame_rate=StrictlyPositiveRational(121, 1), sub_frame=0, dropFrame=False)
 
   def test_timecode_from_dict(self):
     r = TimingTimecode.from_json({
@@ -841,16 +842,17 @@ def test_timecode_from_dict(self):
           "denom": 1
         },
       "subFrame": 0,
+      "dropFrame": False,
     })
     self.assertEqual(str(r), str(Timecode(hours=1, minutes=2, seconds=3, frames=4,
                                           frame_rate=StrictlyPositiveRational(24, 1),
-                                          sub_frame=0)))
+                                          sub_frame=0, dropFrame=False)))
 
   def test_timecode_to_dict(self):
+    # If the explicit sub-frame or drop-frame is the default, it isn't serialized
     j0 = TimingTimecode.to_json(Timecode(hours=1, minutes=2, seconds=3, frames=4,
                                         frame_rate=StrictlyPositiveRational(24, 1),
-                                        sub_frame=0))
-    # since the explicit sub_frame of zero matches the default, it isn't serialized
+                                        sub_frame=0, dropFrame=False))
     self.assertDictEqual(j0, {
       "hours": 1,
       "minutes": 2,
@@ -862,7 +864,7 @@ def test_timecode_to_dict(self):
         }})
     j1 = TimingTimecode.to_json(Timecode(hours=1, minutes=2, seconds=3, frames=4,
                                          frame_rate=StrictlyPositiveRational(24, 1),
-                                         sub_frame=1))
+                                         sub_frame=1, dropFrame=False))
     self.assertDictEqual(j1, {
       "hours": 1,
       "minutes": 2,
@@ -873,6 +875,20 @@ def test_timecode_to_dict(self):
         "denom": 1
       },
       "subFrame": 1})
+    j2 = TimingTimecode.to_json(Timecode(hours=1, minutes=2, seconds=3, frames=4,
+                                         frame_rate=StrictlyPositiveRational(24, 1),
+                                         sub_frame=1, dropFrame=True))
+    self.assertDictEqual(j2, {
+      "hours": 1,
+      "minutes": 2,
+      "seconds": 3,
+      "frames": 4,
+      "frameRate": {
+        "num": 24,
+        "denom": 1
+      },
+      "subFrame": 1,
+      "dropFrame": True})
 
   def test_lens_encoders_limits(self):
     clip = Clip()

src/test/python/test_mosys_reader.py

@@ -35,7 +35,7 @@ def test_reader(self):
     self.assertEqual(str(clip.timing_timecode[8]),
                      str(Timecode(hours=15, minutes=3, seconds=47, frames=10,
                                   frame_rate=StrictlyPositiveRational(25,1),
-                                  sub_frame=0)))
+                                  sub_frame=0, dropFrame=False)))
     self.assertEqual(clip.transforms[9][0].translation, Vector3(x=-8.121, y=-185.368, z=119.806))
     self.assertEqual(clip.transforms[10][0].rotation, Rotator3(pan=-2.969, tilt=-28.03, roll=3.1))
     self.assertEqual(clip.lens_encoders[11], FizEncoders(focus=0.7643280029296875, zoom=0.0014190673828125))