re-jig {color,ir}_camera_params attributes

Make it explicit that camera calibration is only available after device
start.

Author: rjw57

binding/freenect2-c.cpp

@@ -307,15 +307,17 @@ static void freenect2_registration_dispose(Freenect2RegistrationRef reg_ref)
 static void freenect2_registration_apply(
     Freenect2RegistrationRef reg_ref, Freenect2FrameRef rgb_ref,
     Freenect2FrameRef depth_ref, Freenect2FrameRef undistorted_ref,
-    Freenect2FrameRef registered_ref, int enable_filter)
+    Freenect2FrameRef registered_ref, int enable_filter,
+    Freenect2FrameRef big_depth_ref)
 {
     Registration* reg = reinterpret_cast<Registration*>(reg_ref);
     Frame* rgb = reinterpret_cast<Frame*>(rgb_ref);
     Frame* depth = reinterpret_cast<Frame*>(depth_ref);
     Frame* undistorted = reinterpret_cast<Frame*>(undistorted_ref);
     Frame* registered = reinterpret_cast<Frame*>(registered_ref);
+    Frame* big_depth = reinterpret_cast<Frame*>(big_depth_ref);
     reg->apply(rgb, depth, undistorted, registered,
-        (enable_filter != 0) ? true : false);
+        (enable_filter != 0) ? true : false, big_depth);
 }
 
 static void freenect2_registration_get_points_xyz(

binding/freenect2_build.py

@@ -39,6 +39,7 @@
 
 typedef struct {
     float fx, fy, cx, cy, k1, k2, k3, p1, p2;
+    ...;
 } IrCameraParams;
 
 typedef struct {
@@ -65,6 +66,7 @@
     float my_x1y0; // x
     float my_x0y1; // y
     float my_x0y0; // 1
+    ...;
 } ColorCameraParams;
 
 Freenect2Ref freenect2_create(void);
@@ -131,7 +133,8 @@
 void freenect2_registration_apply(
     Freenect2RegistrationRef reg_ref, Freenect2FrameRef rgb_ref,
     Freenect2FrameRef depth_ref, Freenect2FrameRef undistorted_ref,
-    Freenect2FrameRef registered_ref, int enable_filter);
+    Freenect2FrameRef registered_ref, int enable_filter,
+    Freenect2FrameRef big_depth_ref);
 void freenect2_registration_get_points_xyz(
     Freenect2RegistrationRef reg_ref, Freenect2FrameRef undistorted_ref,
     const int32_t* rows, const int32_t* cols, size_t n_points,

freenect2/__init__.py

@@ -1,3 +1,65 @@
+"""
+.. py:class:: ColorCameraParams
+
+    Color camera intrinsic calibration.
+
+    .. py:attribute:: fx
+
+        Focal length for x-axis (pixels)
+
+    .. py:attribute:: fy
+
+        Focal length for y-axis (pixels)
+
+    .. py:attribute:: cx
+
+        Principal point for x-axis (pixels)
+
+    .. py:attribute:: cy
+
+        Principal point for y-axis (pixels)
+
+.. py:class:: IrCameraParams
+
+    IR/depth camera intrinsic calibration.
+
+    .. py:attribute:: fx
+
+        Focal length for x-axis (pixels)
+
+    .. py:attribute:: fy
+
+        Focal length for y-axis (pixels)
+
+    .. py:attribute:: cx
+
+        Principal point for x-axis (pixels)
+
+    .. py:attribute:: cy
+
+        Principal point for y-axis (pixels)
+
+    .. py:attribute:: k1
+
+        Radial distortion co-efficient, 1st-order
+
+    .. py:attribute:: k2
+
+        Radial distortion co-efficient, 2nd-order
+
+    .. py:attribute:: k3
+
+        Radial distortion co-efficient, 3rd-order
+
+    .. py:attribute:: p1
+
+        Tangential distortion co-efficient
+
+    .. py:attribute:: p2
+
+        Tangential distortion co-efficient
+
+"""
 from __future__ import print_function
 
 from contextlib import contextmanager
@@ -106,6 +168,18 @@ class Device(object):
     Raises:
         :py:class:`.NoDeviceError` if there is no default device to open.
 
+    .. py:attribute:: color_camera_params
+
+        (:py:class:`.ColorCameraParams` or None) A structure describing the RGB
+        camera factory calibration. Before the :py:func:`.start` is called, this
+        is *None* since the device only reports calibration when capture begins.
+
+    .. py:attribute:: ir_camera_params
+
+        (:py:class:`.IrCameraParams` or None) A structure describing the IR
+        camera factory calibration. Before the :py:func:`.start` is called, this
+        is *None* since the device only reports calibration when capture begins.
+
     """
 
     def __init__(self, c_object=None):
@@ -121,6 +195,9 @@ def __init__(self, c_object=None):
         self.color_frame_listener = self._default_listener
         self.ir_and_depth_frame_listener = self._default_listener
 
+        self.color_camera_params = None
+        self.ir_camera_params = None
+
     def start(self, frame_listener=None):
         """Start depth, IR and RGB streams.
 
@@ -136,6 +213,9 @@ def start(self, frame_listener=None):
             self.ir_and_depth_frame_listener = frame_listener
         lib.freenect2_device_start(self._c_object)
 
+        self.color_camera_params = lib.freenect2_device_get_color_camera_params(self._c_object)
+        self.ir_camera_params = lib.freenect2_device_get_ir_camera_params(self._c_object)
+
     def stop(self):
         """Stop any running streams."""
         lib.freenect2_device_stop(self._c_object)
@@ -182,18 +262,6 @@ def registration(self):
                 self.ir_camera_params, self.color_camera_params)
         return self._registration
 
-    @property
-    def ir_camera_params(self):
-        """A structure describing the factory calibrated parameters of the IR
-        camera. See the libfreenect2 documentation."""
-        return lib.freenect2_device_get_ir_camera_params(self._c_object)
-
-    @property
-    def color_camera_params(self):
-        """A structure describing the factory calibrated parameters of the RGB
-        camera. See the libfreenect2 documentation."""
-        return lib.freenect2_device_get_color_camera_params(self._c_object)
-
     @property
     def color_frame_listener(self):
         """A callable called whenever a new color frame arrives from the
@@ -434,7 +502,7 @@ def __init__(self, depth_p, rgb_p):
             lib.freenect2_registration_create(depth_p, rgb_p),
             lib.freenect2_registration_dispose)
 
-    def apply(self, rgb, depth, enable_filter=True):
+    def apply(self, rgb, depth, enable_filter=True, with_big_depth=False):
         """Take an RGB and Depth image and return tuple with the undistorted
         depth image and color image rectified onto depth.
 
@@ -443,6 +511,8 @@ def apply(self, rgb, depth, enable_filter=True):
             depth (:py:class:`.Frame`): Depth frame received from device
             enable_filter (bool): If true, filter out pixels not visible in
                 both cameras.
+            with_big_depth (bool): If true, also return a 1920x1082 mapping of
+                depth onto the color map. The top and bottom rows are blank.
 
         Returns:
             A :py:class:`Frame` pair representing the undistorted depth and
@@ -453,12 +523,25 @@ def apply(self, rgb, depth, enable_filter=True):
         undistorted.format = depth.format
         registered = Frame.create(512, 424, 4)
         registered.format = rgb.format
+
+        big_depth, big_depth_ref = None, ffi.NULL
+        if with_big_depth:
+            big_depth = Frame.create(1920, 1082, 4)
+            big_depth.format = depth.format
+            big_depth_ref = big_depth._c_object
+
         lib.freenect2_registration_apply(
             self._c_object,
             rgb._c_object, depth._c_object, undistorted._c_object,
-            registered._c_object, 1 if enable_filter else 0
+            registered._c_object, 1 if enable_filter else 0,
+            big_depth_ref
         )
-        return undistorted, registered
+
+        rvs = [undistorted, registered]
+        if with_big_depth:
+            rvs.append(big_depth)
+
+        return tuple(rvs)
 
     def get_points_xyz(self, undistorted, rows, cols):
         """Retrieve real-world co-ordinates corresponding to points in the