FlyCapture2_Camera-bugfixes: Add google style docstrings to the FlyCapture2Camera device.

Author: dihm

FlyCapture2Camera/blacs_tabs.py

@@ -14,6 +14,10 @@
 from labscript_devices.IMAQdxCamera.blacs_tabs import IMAQdxCameraTab
 
 class FlyCapture2CameraTab(IMAQdxCameraTab):
+    """Thin sub-class of obj:`IMAQdxCameraTab`.
+    
+    This sub-class only defines :obj:`worker_class` to point to the correct
+    :obj:`FlyCapture2CameraWorker`."""
 
     # override worker class
     worker_class = 'labscript_devices.FlyCapture2Camera.blacs_workers.FlyCapture2CameraWorker'

FlyCapture2Camera/blacs_workers.py

@@ -27,10 +27,44 @@
 PyCapture2 = None
 
 class FlyCapture2_Camera(object):
+    """The backend hardware interface class for the FlyCapture2Camera.
+    
+    This class handles all of the API/hardware implementation details for the
+    corresponding labscript device. It is used by the BLACS worker to send
+    appropriate API commands to the camera for the standard BLACS camera operations
+    (i.e. transition_to_buffered, get_attributes, snap, etc).
+    
+    Attributes:
+        camera (PyCapture2.Camera): Handle to connected camera.
+        get_props (list): This list sets which values of each property object 
+            are returned when queried by :obj:`get_attribute`.
+        pixel_formats (IntEnum): An IntEnum object that is automatically 
+            populated with the supported pixel types of the connected camera.
+        width (int): Width of images for most recent acquisition. 
+            Used by :obj:`_decode_image_data` to format images correctly.
+        height (int): Height of images for most recent acquisition.
+            Used by :obj:`_decode_image_data` to format images correctly.
+        pixelFormat (str): Pixel format name for most recent acquisition.
+            Used by :obj:`_decode_image_data` to format images correctly.
+        _abort_acquisition (bool): Abort flag that is polled during buffered
+            acquisitions.
+    """
     def __init__(self, serial_number):
         """Initialize FlyCapture2 API camera.
         
-        Serial number should be of int type."""
+        Searches all cameras reachable by the host using the provided serial
+        number. Fails with API error if camera not found.
+        
+        This function also does a significant amount of default configuration.
+        
+        * It defaults the grab timeout to 1 s
+        * Ensures use of the API's HighPerformanceRetrieveBuffer
+        * Ensures the camera is in Format 7, Mode 0 with full frame readout and MONO8 pixels
+        * If using a GigE camera, automatically maximizes the packet size and warns if Jumbo packets are not enabled on the NIC
+        
+        Args:
+            serial_number (int): serial number of camera to connect to
+        """
 
         global PyCapture2
         import PyCapture2
@@ -109,12 +143,16 @@ def __init__(self, serial_number):
 
     def set_attributes(self, attr_dict):
         """Sets all attribues in attr_dict.
+        
         FlyCapture does not control all settings through same interface,
         so we must do them separately.
-        Interfaces are: {
-            <Standard PROPERTY_TYPE>,
-            'TriggerMode',
-            'ImageMode'}
+        Interfaces are: <Standard PROPERTY_TYPE>, TriggerMode, ImageMode
+            
+        Args:
+            attr_dict (dict): dictionary of property dictionaries to set for the camera.
+                These property dictionaries assume a specific structure, outlined in
+                :obj:`set_attribute`, :obj:`set_trigger_mode` and , :obj:`set_image_mode`
+                methods.
         """
 
         for prop, vals in attr_dict.items():
@@ -128,7 +166,17 @@ def set_attributes(self, attr_dict):
                 self.set_attribute(prop, vals)
 
     def set_trigger_mode(self,trig_dict):
-        """Configures triggering options via Trigger Mode interface."""
+        """Configures triggering options via Trigger Mode interface.
+        
+        Args:
+            trig_dict (dict): dictionary with trigger mode property settings. Allowed keys:
+                
+                * 'onOff': bool
+                * 'polarity': 0,1
+                * 'source': int
+                * 'mode': int
+                
+        """
         trig_mode = self.camera.getTriggerMode()
         for k,v in trig_dict.items():
             setattr(trig_mode,k,v)
@@ -140,7 +188,17 @@ def set_trigger_mode(self,trig_dict):
             raise Exception(msg) from e
 
     def set_image_mode(self,image_settings):
-        """Configures ROI and image control via Format 7, Mode 0 interface."""
+        """Configures ROI and image control via Format 7, Mode 0 interface.
+        
+        Args:
+            image_settings (dict): dictionary of image settings. Allowed keys:
+                
+                * 'pixelFormat': valid pixel format string, i.e. 'MONO8'
+                * 'offsetX': int
+                * 'offsetY': int
+                * 'width': int
+                * 'height': int
+        """
         image_info, supported = self.camera.getFormat7Info(0)
         Hstep = image_info.offsetHStepSize
         Vstep = image_info.offsetVStepSize
@@ -177,13 +235,23 @@ def set_image_mode(self,image_settings):
 
     def set_attribute(self, name, values):
         """Set the values of the attribute of the given name using the provided
-        dictionary values. Typical structure is:
-        values = {'onOff':True,
-                  'autoManualMode':False,
-                  'absControl':True,
-                  'absValue':0.0}
+        dictionary values. 
         
-        Note that invalid settings tend to coerce instead of error."""
+        Generally, absControl should be used to configure settings. Note that
+        invalid settings tend to coerce instead of presenting an error.
+        
+        Args:
+            name (str): 
+            values (dict): Dictionary of settings for the property. Allowed keys are:
+                
+                * 'onOff': bool
+                * 'autoManualMode': bool
+                * 'absControl': bool
+                * 'absValue': float
+                * 'valueA': int
+                * 'valueB': int
+                * 'onePush': bool
+        """
         try:
             prop = self.camera.getProperty(getattr(PyCapture2.PROPERTY_TYPE,name))
 
@@ -198,10 +266,12 @@ def set_attribute(self, name, values):
     def get_attributes(self, visibility_level, writeable_only=True):
         """Return a nested dict of all readable attributes.
         
-        Structure is of form: {
-            <Standard PROPERTY_TYPE>:{},
-            'TriggerMode':{},
-            'ImageMode':{}}
+        Args:
+            visibility_level (str): Not used.
+            writeable_only (:obj:`bool`, optional): Not used
+            
+        Returns:
+            dict: Dictionary of property dictionaries
         """
         props = {}
         prop_names = {prop for prop in dir(PyCapture2.PROPERTY_TYPE) 
@@ -233,7 +303,15 @@ def get_attributes(self, visibility_level, writeable_only=True):
         return props
 
     def get_attribute(self, name):
-        """Return current values dictionary of attribute of the given name"""
+        """Return current values dictionary of attribute of the given name.
+        
+        Args:
+            name (str): Property name to read
+            
+        Returns:
+            dict: Dictionary of property values with structure as defined in
+                :obj:`set_attribute`.
+        """
         try:
             prop_dict = {}
             prop = self.camera.getProperty(getattr(PyCapture2.PROPERTY_TYPE,name))
@@ -245,7 +323,11 @@ def get_attribute(self, name):
             raise Exception(f"Failed to get attribute {name}") from e
 
     def snap(self):
-        """Acquire a single image and return it"""
+        """Acquire a single image and return it
+        
+        Returns:
+            numpy.array: Acquired image
+        """
 
         self.configure_acquisition(continuous=False,bufferCount=1)
         image = self.grab()
@@ -254,9 +336,17 @@ def snap(self):
 
     def configure_acquisition(self, continuous=True, bufferCount=10):
         """Configure acquisition buffer count and grab mode.
-        Continuous mode only keeps most recent frames. Else, keep all frames.
         
-        Also get returned image parameters for formatting purposes.
+        This method also saves image width, heigh, and pixelFormat to class
+        attributes for returned image formatting.
+        
+        Args:
+            continuous (:obj:`bool`, optional): If True, camera will continuously
+                acquire and only keep most recent frames in the buffer. If False,
+                all acquired frames are kept and error occurs if buffer is exceeded.
+                Default is True.
+            bufferCount (:obj:`int`, optional): Number of memory buffers to use 
+                in the acquistion. Default is 10.
         """
         config = self.camera.getConfiguration()
         config.numBuffers = bufferCount
@@ -276,7 +366,11 @@ def configure_acquisition(self, continuous=True, bufferCount=10):
         self.camera.startCapture()
 
     def grab(self):
-        """Grab and return single image during pre-configured acquisition."""
+        """Grab and return single image during pre-configured acquisition.
+        
+        Returns:
+            numpy.array: Returns formatted image
+        """
 
         result = self.camera.retrieveBuffer()
 
@@ -286,7 +380,16 @@ def grab(self):
         return self._decode_image_data(img)
 
     def grab_multiple(self, n_images, images):
-        """Grab n_images into images array during buffered acquistion."""
+        """Grab n_images into images array during buffered acquistion.
+        
+        Grab method involves a continuous loop with fast timeout in order to
+        poll :obj:`_abort_acquisition` for a signal to abort.
+        
+        Args:
+            n_images (int): Number of images to acquire. Should be same number
+                as the bufferCount in :obj:`configure_acquisition`.
+            images (list): List that images will be saved to as they are acquired
+        """
         print(f"Attempting to grab {n_images} images.")
         for i in range(n_images):
             while True:
@@ -304,9 +407,19 @@ def grab_multiple(self, n_images, images):
         print(f"Got {len(images)} of {n_images} images.")
 
     def _decode_image_data(self,img):
-        """FlyCapture2 image buffers require significant formatting.
+        """Formats returned FlyCapture2 API image buffers.
+        
+        FlyCapture2 image buffers require significant formatting.
         This returns what one would expect from a camera.
-        configure_acquisition must be called first to set image format parameters."""
+        :obj:`configure_acquisition` must be called first to set image format parameters.
+        
+        Args:
+            img (numpy.array): A 1-D array image buffer of uint8 values to format
+            
+        Returns:
+            numpy.array: Formatted array based on :obj:`width`, :obj:`height`, 
+                and :obj:`pixelFormat`.
+        """
         pix_fmt = self.pixelFormat
         if pix_fmt.startswith('MONO'):
             if pix_fmt.endswith('8'):
@@ -322,7 +435,12 @@ def _decode_image_data(self,img):
         return image.copy()
 
     def _send_format7_config(self,image_config):
-        """Validates and sends the Format7 configuration packet."""
+        """Validates and sends the Format7 configuration packet.
+        
+        Args:
+            image_config (PyCapture2.Format7ImageSettings): Format7ImageSettings
+                object to validate and send to camera.
+        """
         try:            
             fmt7PktInfo, valid = self.camera.validateFormat7Settings(image_config)
             if valid:
@@ -331,25 +449,33 @@ def _send_format7_config(self,image_config):
             raise RuntimeError('Error configuring image settings') from e
 
     def stop_acquisition(self):
+        """Tells camera to stop current acquistion."""
         self.camera.stopCapture()
 
     def abort_acquisition(self):
+        """Sets :obj:`_abort_acquisition` flag to break buffered acquisition loop."""
         self._abort_acquisition = True
 
     def close(self):
+        """Closes :obj:`camera` handle to the camera."""
         self.camera.disconnect()
 
 
 class FlyCapture2CameraWorker(IMAQdxCameraWorker):
     """FlyCapture2 API Camera Worker. 
     
-    Inherits from IMAQdxCameraWorker. Overloads get_attributes_as_dict 
-    to use FlyCapture2Camera.get_attributes() method."""
+    Inherits from obj:`IMAQdxCameraWorker`. Defines :obj:`interface_class` and overloads
+    :obj:`get_attributes_as_dict` to use FlyCapture2Camera.get_attributes() method."""
     interface_class = FlyCapture2_Camera
 
     def get_attributes_as_dict(self, visibility_level):
         """Return a dict of the attributes of the camera for the given visibility
-        level"""
+        level
+        
+        Args:
+            visibility_level (str): Normally configures level of attribute detail
+                to return. Is not used by FlyCapture2_Camera.
+        """
         if self.mock:
             return IMAQdxCameraWorker.get_attributes_as_dict(self,visibility_level)
         else:

FlyCapture2Camera/labscript_devices.py

@@ -14,5 +14,7 @@
 from labscript_devices.IMAQdxCamera.labscript_devices import IMAQdxCamera
 
 class FlyCapture2Camera(IMAQdxCamera):
+    """Thin sub-class of :obj:`IMAQdxCamera`."""
+    
     description = 'FlyCapture2 Camera'