Pinhole_focal_length, not focal_length; adjust readers to set nominal_focal_length. Note that nominal focal length for a zoom lens will be undefined in 1.0.0.

Author: JGoldstone

src/main/python/camdkit/arri/reader.py

@@ -79,7 +79,10 @@ def to_clip(csv_path: str) -> camdkit.model.Clip:
         height=pix_dims.height * pixel_pitch / 1000.0
       )
 
-    clip.lens_focal_length = tuple(float(m["Lens Focal Length"]) for m in csv_data)
+    focal_lengths = set([m["Lens Focal Length"] for m in csv_data])
+    if len(focal_lengths) == 1:
+      focal_length = float(focal_lengths.pop())
+      clip.lens_nominal_focal_length = focal_length
 
     clip.lens_focus_distance = tuple(float(m["Lens Focus Distance"]) for m in csv_data)
 

src/main/python/camdkit/bmd/reader.py

@@ -109,7 +109,10 @@ def to_clip(metadata_file: typing.IO) -> camdkit.model.Clip:
   # sampled metadata
 
   # focal_length
-  clip.lens_focal_length = tuple(float(m["focal_length"][:-2]) for m in frame_data)
+    focal_lengths = set([m["focal_length"][:-2] for m in frame_data])
+    if len(focal_lengths) == 1:
+      focal_length = float(focal_lengths.pop())
+      clip.lens_nominal_focal_length = focal_length
 
   # focus_position
   clip.lens_focus_distance = tuple(float(m["distance"][:-2]) for m in frame_data)

src/main/python/camdkit/canon/reader.py

@@ -61,7 +61,10 @@ def to_clip(static_csv: typing.IO, frames_csv: typing.IO) -> camdkit.model.Clip:
   # sampled metadata
 
   # focal_length
-  clip.lens_focal_length = tuple(Fraction(m["FocalLength"]) for m in frame_data)
+  focal_lengths = set(Fraction(m["FocalLength"]) for m in frame_data)
+  if len(focal_lengths) == 1:
+    focal_length = float(focal_lengths.pop())
+    clip.lens_nominal_focal_length = focal_length
 
   # focus_position
   clip.lens_focus_distance = tuple(_read_float32_as_hex(m["FocusPosition"]) for m in frame_data)

src/main/python/camdkit/examples.py

@@ -26,7 +26,7 @@ def _unwrap_clip_to_pseudo_frame(wrapped_clip: JsonSchemaValue) -> JsonSchemaVal
     ("lens", "entrancePupilOffset"),
     ("lens", "exposureFalloff"),
     ("lens", "fStop"),
-    ("lens", "focalLength"),
+    ("lens", "pinholeFocalLength"),
     ("lens", "focusDistance"),
     ("lens", "projectionOffset"),
     ("lens", "rawEncoders"),
@@ -160,7 +160,7 @@ def _get_recommended_dynamic_clip():
   clip.transforms = ((Transform(translation=v, rotation=r, id="Camera"),),)
   # lens
   clip.lens_f_number = (4.0,)
-  clip.lens_focal_length = (24.305,)
+  clip.lens_pinhole_focal_length = (24.305,)
   clip.lens_focus_distance = (10.0,)
   clip.lens_entrance_pupil_offset = (0.123,)
   clip.lens_encoders = (FizEncoders(focus=0.1, iris=0.2, zoom=0.3),)

src/main/python/camdkit/lens_types.py

@@ -262,13 +262,12 @@ class Lens(CompatibleBaseModel):
     by the diameter of the entrance pupil.
     """
 
-    # TODO: file issue to get this renamed to lens_pinhole_focal_length in the clip and pinholeFocalLength in the JSON
-    focal_length: Annotated[tuple[NonNegativeFloat, ...] | None,
-      Field(alias="focalLength",
+    pinhole_focal_length: Annotated[tuple[NonNegativeFloat, ...] | None,
+      Field(alias="pinholeFocalLength",
             json_schema_extra={"units": MILLIMETER,
-                               "clip_property": "lens_focal_length",
+                               "clip_property": "lens_pinhole_focal_length",
                                "constraints": NON_NEGATIVE_REAL})] = None
-    """Focal length of the lens."""
+    """Distance between the pinhole and the image plane in the simple CGI pinhole camera model."""
 
     focus_distance: Annotated[tuple[StrictlyPositiveFloat, ...] | None,
       Field(alias="focusDistance",

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

@@ -280,7 +280,7 @@ def get_tracking_frame(self) -> Clip:
       # Assuming a full frame 35mm active sensor 36x24mm
       # f = 36/[2*tand(FoV/2)]
       fov_radians = fov_h * math.pi / 180.0
-      frame.lens_focal_length = (36.0 / (2.0 * math.tan(fov_radians/2.0)),)
+      frame.lens_pinhole_focal_length = (36.0 / (2.0 * math.tan(fov_radians/2.0)),)
       frame.lens_encoders = (FizEncoders(focus, iris, zoom),)
       frame.lens_distortions = ((Distortion([k1, k2],),),)
       frame.lens_projection_offset = (ProjectionOffset(cx, cy),)

src/main/python/camdkit/red/reader.py

@@ -77,7 +77,10 @@ def to_clip(meta_3_file: typing.IO, meta_5_file: typing.IO) -> camdkit.model.Cli
 
   clip.shutter_angle = float(clip_metadata["Shutter (deg)"])
 
-  clip.lens_focal_length = tuple(int(m["Focal Length"]) for m in csv_data)
+  focal_lengths = set([float(m["Focal Length"]) for m in csv_data])
+  if len(focal_lengths) == 1:
+    focal_length = float(focal_lengths.pop())
+    clip.lens_nominal_focal_length = focal_length
 
   clip.lens_focus_distance = tuple(int(m["Focus Distance"]) for m in csv_data)
 

src/main/python/camdkit/venice/reader.py

@@ -190,7 +190,10 @@ def to_clip(static_file: typing.IO, dynamic_file: typing.IO) -> camdkit.model.Cl
 
   clip.duration = len(csv_data)/clip_fps
 
-  clip.lens_focal_length = tuple(float(m["Focal Length (mm)"]) for m in csv_data)
+  focal_lengths = set([float(m["Focal Length (mm)"]) for m in csv_data])
+  if len(focal_lengths) == 1:
+    focal_length = float(focal_lengths.pop())
+    clip.lens_nominal_focal_length = focal_length
 
   clip.lens_focus_distance = tuple(float(m["Focus Distance (ft)"]) * 12.0 * 25.4 / 1000.0 for m in csv_data)
 

src/test/python/test_arri_reader.py

@@ -38,7 +38,7 @@ def test_reader(self):
 
     self.assertEqual(clip.capture_frame_rate, 24)
 
-    self.assertEqual(clip.lens_focal_length[0], 40)
+    self.assertEqual(clip.lens_nominal_focal_length, 40)
 
     self.assertEqual(clip.lens_focus_distance[0], 4.812)
 

src/test/python/test_bmd_reader.py

@@ -39,7 +39,7 @@ def test_reader(self):
 
     self.assertEqual(clip.capture_frame_rate, 48)
 
-    self.assertEqual(clip.lens_focal_length[0], 50)
+    self.assertEqual(clip.lens_nominal_focal_length, 50)
 
     self.assertEqual(clip.lens_focus_distance[0], 991)