wasatch 2.3.2__py3-none-any.whl

wasatch/IDSCamera.py

@@ -0,0 +1,916 @@
+import threading
+import logging
+import pathlib 
+import numpy as np
+import time
+import sys
+import os
+
+from datetime import datetime
+
+from ids_peak import ids_peak as IDSPeak
+from ids_peak import ids_peak_ipl_extension as EXT
+from ids_peak_ipl import ids_peak_ipl as IPL
+
+from wasatch.AreaScanImage import AreaScanImage
+from wasatch import utils
+
+log = logging.getLogger(__name__)
+
+class IDSCamera:
+    """
+    This class encapsulates access to the IDS Peak SDK. It is called and used by
+    IDSDevice. IDSDevice "is-an" InterfaceDevice, and is mimicking the same 
+    upstream API as WasatchDevice, TCPDevice, AndorDevice etc. This class, 
+    IDSCamera, is implementing the downstream IDSPeak SDK API.
+
+    We could have done this like AndorDevice and TCPDevice, and merged both 
+    IDSDevice and IDSCamera into a single file or class (upstream and downsteam 
+    APIs). However, I opted to follow the example of (WasatchDevice -> 
+    FeatureInterfaceDevice) and (OceanDevice -> SeaBreezeWrapper), both of which
+    keep the two separate.
+
+    @par Vendor Documentation
+
+    @see https://www.ids-imaging.us/manuals/ids-peak/ids-peak-api-documentation/2.15.0/en/annotated.html
+    @see https://en.ids-imaging.com/manuals/ids-peak/ids-peak-ipl-documentation/2.15.0/en/annotated.html
+                                                              ^^^--- different!
+    @see Program Files/IDS/ids_peak/generic_sdk/samples/source/python/start_stop_acquisition_software_trigger/main.py
+    
+
+    @par Converting IDS --> Qt
+
+    Per cpp/multi_camera_live_qtwidgets/acquisitionworker.cpp, it looks like:
+
+        peak::ipl::PixelFormatName::BGRa8    --> QImage::Format_RGB32
+        peak::ipl::PixelFormatName::RGB8     --> QImage::Format_RGB888
+        peak::ipl::PixelFormatName::RGB10p32 --> QImage::Format_BGR30
+        peak::ipl::PixelFormatName::BayerRG8 --> QImage::Format_Grayscale8
+        peak::ipl::PixelFormatName::Mono8    --> QImage::Format_Grayscale8
+        otherwise                            --> QImage::Format_RGB32
+
+    @par NodeMap
+
+    As generated by dump_node("Root"):
+
+          Root (Category) = 
+            TLParamsLockedCategory (Category) = 
+              TLParamsLocked (Integer) = 0 
+            AcquisitionControl (Category) = 
+       -->    AcquisitionMode (Enumeration) = Continuous (SingleFrame, MultiFrame, Continuous)
+              AcquisitionFrameCount (Integer) = 1 
+              SensorShutterMode (Enumeration) = Rolling 
+       -->    AcquisitionAbort (Command)
+              AcquisitionFrameRateTarget (Float) = 20.0 Hz
+              SensorFrameTimeClocksTarget (Integer) = 1856250 
+              AcquisitionFrameRateTargetEnable (Boolean) = False
+       -->    AcquisitionStart (Command)
+       -->    AcquisitionStop (Command)
+              TriggerSelector (Enumeration) = ReadOutStart 
+       -->    TriggerMode (Enumeration) = On (Off, On)
+       -->    TriggerSource (Enumeration) = Software (Software, Line0)
+              TriggerActivation (Enumeration) = RisingEdge
+       -->    TriggerSoftware (Command)
+       -->    TriggerDelay (Float) = 0.0 us
+              TriggerDivider (Integer) = 1 
+              SensorClockFrequency (Integer) = 37125000 Hz
+       ==>    ExposureTime (Float) = 15006.38383838384 us
+              SensorExposureTimeClocks (Integer) = 557112 
+       -->    AcquisitionFrameRate (Float) = 54.910841063990915 Hz
+              SensorFrameTimeClocks (Integer) = 676096 
+              ExposureMode (Enumeration) = Timed 
+            TransferControl (Category) = 
+              TransferControlMode (Enumeration) = Automatic 
+            DeviceControl (Category) = 
+       -->    DeviceFirmwareVersion (String) = 3.30.21242
+              DeviceUserID (String) = 
+              DeviceReset (Command)
+              DeviceBootStatus (Enumeration) = OK (OK, WatchdogReboot, RepeatedWatchdogError, WatchdogRebootAfterRepeatedWatchdogError, FirmwareCorruptionError, WatchdogRebootAfterFirmwareCorruptionError, FirmwareMissingError, WatchdogRebootAfterFirmwareMissingError, BootDataCorruptionError, WatchdogRebootAfterBootDataCorruptionError, CriticalErrorReboot, CriticalErrorWhileStarting, CriticalErrorWhileConfiguring, CriticalUSBErrorReboot, CriticalCoreErrorReboot)
+              DeviceBootStatusAdditionalInfo1 (Integer) = 0 
+              DeviceBootStatusAdditionalInfo2 (Integer) = 0 
+       ==>    DeviceLinkSpeed (Integer) = 500_000_000 Bps (SuperSpeed USB 5Gbps per https://www.1stvision.com/cameras/IDS/IDS-manuals/en/device-link-speed.html)
+              DeviceSFNCVersionMajor (Integer) = 2 
+              DeviceSFNCVersionMinor (Integer) = 7 
+              DeviceSFNCVersionSubMinor (Integer) = 0 
+              ResetToFactoryDefaults (Command)
+              BootOptions (Enumeration) = Runtime (Runtime, Service)
+              DeviceScanType (Enumeration) = Areascan 
+              SensorOperationModeRaw (Enumeration) = Default 
+              SensorOperationMode (Enumeration) = Default (LongExposure, Default, Linescan, LinescanSensor, HighSpeed)
+       -->    DeviceVendorName (String) = IDS Imaging Development Systems GmbH
+       -->    DeviceModelName (String) = U3-38CxXCP-M
+              DeviceFamilyName (String) = U3-XCP
+       -->    DeviceManufacturerInfo (String) = U3-38C0XCP-M-GL Rev.1.2
+       ==>    DeviceSerialNumber (String) = 4108809482
+       -->    DeviceVersion (String) = 18.22.1.1.10000BC.1.352
+              DeviceRegistersStreamingStart (Command)
+              DeviceRegistersStreamingEnd (Command)
+              DeviceRegistersValid (Boolean) = True
+       -->    DeviceLinkAcquisitionFrameRateLimit (Float) = 54.91084 Hz
+              DeviceLinkThroughputLimit (Integer) = 162_000_000 Bps
+              DeviceLinkCurrentThroughput (Integer) = 161_587_230 Bps
+              DeviceLinkThroughputLimitComponent (Enumeration) = Sensor (Link, Sensor)
+              DeviceClockSelector (Enumeration) = Sensor 
+              DeviceClockFrequency (Float) = 37125000.0 Hz
+       -?>    DeviceOpticalFilterType (Enumeration) = GL (Unknown, None, HQ, GL, DL)
+            TestControl (Category) = 
+              TestPendingAck (Integer) = 0 ms
+              TriggerEventTest (Command)
+              TestEventGenerate (Command)
+            ManufacturerInfo (Category) = 
+              LogicBoardType (Integer) = 24 
+              LogicBoardFirehare (Integer) = 22 
+              SensorBoardType (Integer) = 16777404 
+              SensorBoardFirehare (Integer) = 1 
+              ConnectorBoardType (Integer) = 1 
+              ConnectorBoardFirehare (Integer) = 1 
+              OpticControlPossible (Boolean) = False
+            FileAccessControl (Category) = 
+              FileSelector (Enumeration) = UserData1 (UserData1, UserData2, CriticalEventLog)
+        -?>   FileAccessBuffer (Register) = 0x80028e94 (len 480) (is this a 480-byte writable EEPROM? https://www.1stvision.com/cameras/IDS/IDS-manuals/en/file-access-buffer.html)
+              FileOperationSelector (Enumeration) = Open (Open, Delete)
+              FileOperationExecute (Command)
+        -->   FileOpenMode (Enumeration) = Write (Read, Write)
+              FileOpenStatus (Enumeration) = Close (Close, OpenRead, OpenWrite)
+              FileOperationStatus (Enumeration) = Success (Success, Failure)
+              FileOperationResult (Integer) = 0 
+              FileSize (Integer) = 0 B
+            SequencerControl (Category) = 
+              SequencerMode (Enumeration) = Off (On, Off)
+              SequencerConfigurationMode (Enumeration) = Off (On, Off)
+            EventControl (Category) = 
+              EventSelector (Enumeration) = EventDropped (Error, CriticalError, EventDropped)
+              EventReset (Command)
+              EventNotification (Enumeration) = On (Off, On, Once)
+              EventTestData (Category) = 
+                EventTest (Integer) = 20479 
+              EventErrorData (Category) = 
+                EventError (Integer) = 36880 
+              EventCriticalErrorData (Category) = 
+                EventCriticalError (Integer) = 36881 
+              EventEventDroppedData (Category) = 
+                EventEventDropped (Integer) = 36882 
+            UserSetControl (Category) = 
+              UserSetSelector (Enumeration) = Default (Default, UserSet0, UserSet1)
+              UserSetLoad (Command)
+              UserSetSave (Command)
+              UserSetDefault (Enumeration) = Default (Default)
+              UserSetFeatureSelector (Enumeration) = Roi (Core, Roi)
+              UserSetFeatureEnable (Boolean) = True
+            ProtectionControl (Category) = 
+              ProtectionPassword (String) = 
+              ProtectionPasswordCheck (Command)
+              ProtectionNodeLockSelector (Enumeration) = DeviceManufacturerInfo (DeviceManufacturerInfo, DeviceUserID, UserData1, UserData2)
+              ProtectionNodeLockEnable (Boolean) = True
+              ProtectionReset (Command)
+              ProtectionSave (Command)
+            LEDControl (Category) = 
+              LEDSelector (Enumeration) = LEDStatus (LEDStatus)
+              LEDTriggerSource (Enumeration) = CameraStatus (Off, CameraStatus, BlinkingSlow, BlinkingFast)
+        ==> DigitalIOControl (Category) = 
+              LineSelector (Enumeration) = Line0 (Line0, Line1, Line2, Line3) (https://www.1stvision.com/cameras/IDS/IDS-manuals/en/line-selector.html)
+              LineMode (Enumeration) = Input (Input, Output)
+              LineFormat (Enumeration) = LVTTL 
+              UserOutputSelector (Enumeration) = UserOutput0 (UserOutput0, UserOutput1, UserOutput2, UserOutput3) (https://www.1stvision.com/cameras/IDS/IDS-manuals/en/user-output-selector.html)
+              UserOutputValue (Boolean) = False
+            ImageFormatControl (Category) = 
+         -->  SensorWidth (Integer) = 1936 
+              SensorPixelSize (Enumeration) = Bpp10 
+              IsPixelSizeAvailable (Integer) = 2 
+         -->  SensorHeight (Integer) = 1096 
+              WidthMax (Integer) = 1936 
+              HeightMax (Integer) = 1096 
+         ==>  Width (Integer) = 1920 
+         ==>  Height (Integer) = 1080 
+              OffsetX (Integer) = 8 
+              OffsetY (Integer) = 8 
+              BinningSelector (Enumeration) = Sensor 
+              BinningHorizontal (Integer) = 1 
+         -*?  BinningVertical (Integer) = 1 
+              BinningHVInvalidator (Integer) = 1 
+         -->  TestPattern (Enumeration) = Off (Off, Black, White, ColorBar, ColorBarVertical)
+         ==>  PixelSize (Enumeration) = Bpp10 (Bpp1, Bpp2, Bpp4, Bpp8, Bpp10, Bpp12, Bpp14, Bpp16, Bpp24, Bpp30, Bpp32, Bpp36, Bpp48, Bpp64)
+         ==>  PixelColorFilter (Enumeration) = None (None, BayerRG, BayerGB, BayerGR, BayerBG)
+         ==>  PixelFilter (Enumeration) = None (None, BayerRG, BayerGB, BayerGR, BayerBG)
+              ComponentSelector (Enumeration) = Intensity 
+              ComponentEnable (Boolean) = True
+              ComponentEnableAll (Integer) = 1 
+         ==>  PixelFormat (Enumeration) = Mono10g40IDS (Mono10g40IDS, Mono12g24IDS)
+         ==>  SensorName (String) = Sony IMX662-AAMR-C
+         -->  SensorPixelWidth (Float) = 2.9 um
+         -->  SensorPixelHeight (Float) = 2.9 um
+         -->  ReverseX (Boolean) = False
+         -->  ReverseY (Boolean) = False
+            AnalogControl (Category) = 
+              PixelDepthBitPerChannel (Integer) = 10 
+              GainSelector (Enumeration) = AnalogAll 
+         ==>  Gain (Float) = 1.0 
+                    (range unclear -- see https://www.1stvision.com/cameras/IDS/IDS-manuals/en/gain.html)
+                    (unit unclear; possibly just a floating-point multiplier, not dB, since default is 1.0?)
+              BlackLevelSelector (Enumeration) = Offset10Bit (All8Bit, All10Bit, All12Bit, All14Bit, All16Bit, Offset8Bit, Offset10Bit, Offset12Bit, Offset14Bit, Offset16Bit)
+                    (https://www.1stvision.com/cameras/IDS/IDS-manuals/en/black-level-selector.html)
+              BlackLevel (Float) = 0.0 DN
+              BlackLevelInt (Integer) = 0 
+         XX>  BlackLevelAuto (Enumeration) = ContinuousWithOffset (unclear if this can be disabled -- see https://www.1stvision.com/cameras/IDS/IDS-manuals/en/black-level-auto.html)
+            TransportLayerControl (Category) = 
+              PayloadSize (Integer) = 2_592_000 
+
+    @par Backlog
+
+    The following need to be made much faster, via increased use of NumPy etc:
+
+    - vertical binning
+    - conversion to QPixmap
+
+    """
+
+    INITIALIZED = False
+
+    # @see site-packages/ids_peak_ipl/ids_peak_ipl.py
+    ALL_PIXEL_FORMAT_NAMES = [
+        "BGR10",        "BGR10p32",        "BGR12",          "BGR8",        "BGRa10",          "BGRa12",       "BGRa8",
+        "BayerBG10",    "BayerBG10g40IDS", "BayerBG10p",     "BayerBG12",   "BayerBG12g24IDS", "BayerBG12p",   "BayerBG8",
+        "BayerGB10",    "BayerGB10g40IDS", "BayerGB10p",     "BayerGB12",   "BayerGB12g24IDS", "BayerGB12p",   "BayerGB8",
+        "BayerGR10",    "BayerGR10g40IDS", "BayerGR10p",     "BayerGR12",   "BayerGR12g24IDS", "BayerGR12p",   "BayerGR8",
+        "BayerRG10",    "BayerRG10g40IDS", "BayerRG10p",     "BayerRG12",   "BayerRG12g24IDS", "BayerRG12p",   "BayerRG8",
+        "Confidence16", "Confidence8",     "Coord3D_ABC32f", "Coord3D_C16", "Coord3D_C32f",    "Coord3D_C8",
+        "Mono10",       "Mono12",          "Mono10p",        "Mono12p",     "Mono10g40IDS",    "Mono12g24IDS", "Mono16", "Mono8",
+        "RGB10",        "RGB10p32",        "RGB12",          "RGB8",        "RGBa10",          "RGBa12",       "RGBa8",
+        "YUV420_8_YY_UV_SemiplanarIDS",    "YUV420_8_YY_VU_SemiplanarIDS",  "YUV422_8_UYVY",   "Invalid"
+    ]
+
+    # generated via ImageConverter.SupportedOutputPixelFormatNames(PixelFormat(IPL.PixelFormatName_Mono10g40IDS))
+    # "Mono12g24IDS" omitted as unusable (can't be accessed as line data, can't be output to PNG)
+    SUPPORTED_CONVERSIONS = [ 
+        "Mono16", "Mono12", "Mono10", "Mono8",
+        "RGB12",  "RGB10",  "RGB8",
+        "BGR12",  "BGR10",  "BGR8",
+        "RGBa12", "RGBa10", "RGBa8",
+        "BGRa12", "BGRa10", "BGRa8"
+    ] 
+
+    ############################################################################
+    # Lifecycle
+    ############################################################################
+
+    def __init__(self):
+
+        self.device = None
+        self.node_map = None
+        self.long_name = None
+        self.datastream = None
+
+        self.area_scan_enabled = False
+        self.take_one_request = None
+        self.taking_acquisition = False
+        self.shutdown_in_progress = False
+        self.last_asi_timestamp = None
+        self.last_area_scan_image = None
+        self.area_scan_image_timeout_sec = 1 # by default, generate new ASI at 1Hz
+        self.rotate_180 = True
+        self.shrink_area_scan = True
+        self.degrade_area_scan = True
+
+        self.buffers = []
+
+        # correspond to EEPROM
+        self.model_name = None
+        self.serial_number = None
+        self.width = 0
+        self.height = 0
+        self.start_line = 0
+        self.stop_line = 0
+        self.integration_time_ms = 15 # seems to be default?
+        self.last_integration_time_ms = 15
+
+        self.image_converter = None
+        self.image_transformer = None
+        # self.binning = None
+
+        # this is the default value, but IDSDevice may change it at runtime based
+        # on the ENLIGHTEN plugin
+        self.output_format_name = "Mono16"
+        self.output_format_obj = None
+
+        self.dir = os.path.join(utils.get_default_data_dir(), "idspeak")
+        pathlib.Path(self.dir).mkdir(exist_ok=True)
+
+        try:
+            if self.INITIALIZED:
+                log.debug("IDSPeak.Library already initialized")
+            else:
+                log.debug("initializing IDSPeak.Library")
+                IDSPeak.Library.Initialize()
+                self.INITIALIZED = True
+            self.device_manager = IDSPeak.DeviceManager.Instance()
+            self.init_pixel_format_names()
+        except:
+            log.critical("failed to instantiate IDSPeak.DeviceManager", exc_info=1)
+
+    def init_pixel_format_names(self):
+        """ 
+        If there's an in-built API method to convert from the name of a desired 
+        format to a PixelFormat object or number, I didn't see one. (Okay, maybe
+        using Node.Entries() and SymbolicValue().)
+
+        @see IPL.PixelFormat class docs at https://en.ids-imaging.com/manuals/ids-peak/ids-peak-ipl-documentation/2.15.0/en/classpeak_1_1ipl_1_1_pixel_format.html
+        """
+        self.name_to_num = {}
+        log.debug("All PixelFormat types:")
+        for name in self.ALL_PIXEL_FORMAT_NAMES:
+            num = getattr(IPL, f"PixelFormatName_{name}") # int
+            fmt = IPL.PixelFormat(num) # num -> PixelFormat is easy
+            log.debug(f"  {name:30} = 0x{num:08x} ({num})")
+            assert name == fmt.Name(), f"name {name} != Name() {fmt.Name()}"
+            assert num == fmt.PixelFormatName(), f"num {num} != PixelFormatName() {fmt.PixelFormatName()}" # poorly named
+            self.name_to_num[name] = num
+
+    def close(self):
+        log.debug("close: start")
+        self.stop()
+        try:
+            if self.datastream is not None:
+                log.debug("close: revoking buffers")
+                for buffer in self.datastream.AnnouncedBuffers():
+                    self.datastream.RevokeBuffer(buffer)
+        except:
+            log.error(f"close: caught exception when clearing buffers", exc_info=1)
+        log.debug("close: done")
+
+    def __del__(self):
+        self.close()
+
+    def __repr__(self):
+        return self.long_name
+
+    def connect(self):
+        log.debug("connect: start")
+        self.device_manager.Update()
+        if self.device_manager.Devices().empty():
+            log.debug("connect: no devices found :-(")
+            return False
+
+        # List all available devices
+        log.debug("connect: found device(s):")
+        for device in self.device_manager.Devices():
+            model_name  = device.ModelName()
+            parent_intf = device.ParentInterface().DisplayName()
+            parent_name = device.ParentInterface().ParentSystem().DisplayName()
+            parent_ver  = device.ParentInterface().ParentSystem().Version()
+            long_name = f"{model_name} {parent_intf} ({parent_name} {parent_ver})"
+            log.debug(f"  {long_name}")
+            if self.long_name is None:
+                self.long_name = long_name
+
+        # Open the first device in control mode
+        self.device = self.device_manager.Devices()[0].OpenDevice(IDSPeak.DeviceAccessType_Control)
+
+        # Get device's control nodes
+        self.node_map = self.device.RemoteDevice().NodeMaps()[0]
+
+        # Cache settings corresponding to Wasatch EEPROM
+        self.model_name = device.ModelName()
+        self.serial_number = self.node_map.FindNode("DeviceSerialNumber").Value()
+        self.width = self.node_map.FindNode("Width").Value()
+        self.height = self.node_map.FindNode("Height").Value()
+        self.last_integration_time_ms = self.node_map.FindNode("ExposureTime").Value() / 1000.0
+
+        self.start_line = 0
+        self.stop_line = self.height - 1
+
+        # Load the default settings
+        self.node_map.FindNode("UserSetSelector").SetCurrentEntry("Default")
+        self.node_map.FindNode("UserSetLoad").Execute()
+        self.node_map.FindNode("UserSetLoad").WaitUntilDone()
+
+        # initialize software trigger
+        # @see https://www.ids-imaging.us/manuals/ids-peak/ids-peak-user-manual/2.15.0/en/acquisition-control.html
+        log.debug("TriggerSelector set to ExposureStart")
+        self.node_map.FindNode("TriggerSelector").SetCurrentEntry("ReadOutStart") # "ExposureStart" not supported?
+        self.node_map.FindNode("TriggerMode").SetCurrentEntry("On")
+        self.node_map.FindNode("TriggerSource").SetCurrentEntry("Software")
+        self.node_map.FindNode("ExposureTime").SetValue(15_000) # value in µs
+        
+        # nodeMapRemoteDevice.FindNode("SequencerMode")   .SetCurrentEntry("Off")
+        # nodeMapRemoteDevice.FindNode("AcquisitionMode") .SetCurrentEntry("SingleFrame")
+        # nodeMapRemoteDevice.FindNode("ExposureMode")    .SetCurrentEntry("Timed")
+        # nodeMapRemoteDevice.FindNode("ExposureAuto")    .SetCurrentEntry("Off")
+        # nodeMapRemoteDevice.FindNode("TriggerSelector") .SetCurrentEntry("ExposureStart")
+        # nodeMapRemoteDevice.FindNode("ExposureTime")    .SetValue(400_000) # value in µs
+        # nodeMapRemoteDevice.FindNode("AcquisitionStart").Execute()
+        # nodeMapRemoteDevice.FindNode("AcquisitionStart").WaitUntilDone()
+
+        self.dump_node(name="Root")
+
+        log.debug(f"connect: successfully connected to {self.long_name}")
+        return True
+
+    ############################################################################
+    # Acquisition Loop (Device)
+    ############################################################################
+
+    def set_rotate_180(self, flag):
+        # Setting this once in the camera firmware would be more efficient than
+        # calling self.image_transformer.MirrorUpDownLeftRightInPlace(converted) 
+        # on every image received, but sadly the nodes seem not writable :-(
+        #
+        # self.node_map.FindNode("ReverseX").SetValue(flag)
+        # self.node_map.FindNode("ReverseY").SetValue(flag)
+        self.rotate_180 = flag
+
+    def set_start_line(self, n):
+        self.start_line = n
+        
+    def set_stop_line(self, n):
+        self.stop_line = n
+
+    def set_integration_time_ms(self, ms):
+        # do we need to .stop and .start around this?
+        us = ms * 1000.0
+
+        node = self.node_map.FindNode("ExposureTime")
+        us = max(us, node.Minimum())
+        us = min(us, node.Maximum())
+
+        log.debug(f"set_integration_time_ms: integration time {us} µs")
+        self.node_map.FindNode("ExposureTime").SetValue(us)
+        self.integration_time_ms = ms
+        return ms
+
+    def set_gain_factor(self, factor):
+        node = self.node_map.FindNode("Gain")
+        factor = max(factor, node.Minimum())
+        factor = min(factor, node.Maximum())
+
+        log.debug(f"set_gain: factor {factor:.1f}")
+        self.node_map.FindNode("Gain").SetValue(factor)
+        return factor
+
+    def start(self):
+        log.debug("start: starting")
+        if self.device is None:
+            log.debug("start: no device")
+            return 
+
+        if self.taking_acquisition:
+            log.debug("start: already running")
+            return
+
+        # self.datastream = None # kludge
+        if self.datastream is None:
+            log.debug("start: initializing datastream")
+            self.datastream = self.device.DataStreams()[0].OpenDataStream()
+            log.debug(f"start: datastream initialized")
+            self.reset()
+        else:
+            log.debug("start: datastream already initialized?")
+
+        log.debug("start: queueing buffers")
+        for buffer in self.buffers:
+            self.datastream.QueueBuffer(buffer)
+
+        try:
+            # Lock parameters that should not be accessed during acquisition
+            # MZ: what are these?
+            log.debug("start: locking parameters")
+            self.node_map.FindNode("TLParamsLocked").SetValue(1)
+
+            # determine initial camera output format (the "input format" to this class)
+            input_format_node  = self.node_map.FindNode("PixelFormat")
+            input_format_entry = input_format_node.CurrentEntry()
+            input_format_num   = input_format_entry.Value()
+            self.input_format_obj = IPL.PixelFormat(input_format_num)
+            input_format_name  = self.input_format_obj.Name()
+
+            log.debug(f"start: width {self.width}, height {self.height}, outputting {input_format_name} 0x{input_format_num:08x} ({input_format_num})")
+
+            # Pre-allocate conversion buffers to speed up image conversion
+            # while the acquisition is running
+            if self.image_converter is None:
+                self.init_image_converter()
+
+                # use this opportunity to report all the different conversion 
+                # options from the sensor's default format (the INPUT format to 
+                # this class), which is likely "Mono10g40IDS" or "Mono12g24IDS"
+                log.debug(f"start: supported conversions from {input_format_name}:")
+                for num in self.image_converter.SupportedOutputPixelFormatNames(self.input_format_obj):
+                    fmt = IPL.PixelFormat(num)
+                    name = fmt.Name()
+                    log.debug(f"  {name:30} = 0x{num:08x} ({num})")
+
+            if self.image_transformer is None:
+                self.image_transformer = IPL.ImageTransformer()
+
+            # if self.binning is None:
+            #     self.init_binning()
+
+            self.datastream.StartAcquisition()
+            self.node_map.FindNode("AcquisitionStart").Execute()
+            self.node_map.FindNode("AcquisitionStart").WaitUntilDone()
+            self.taking_acquisition = True
+
+            log.debug("start: started")
+        except:
+            log.error(f"Exception (start acquisition)", exc_info=1)
+
+        log.debug("start: done")
+
+    def init_image_converter(self, output_format_name=None):
+        self.image_converter = IPL.ImageConverter()
+
+        if output_format_name is None:
+            output_format_name = self.output_format_name
+        else:
+            self.output_format_name = output_format_name
+
+        # MZ: I'm not sure if this actually speeds ALL conversions, or just the FIRST one
+        output_format_num = self.name_to_num[self.output_format_name]
+        self.output_format_obj = IPL.PixelFormat(output_format_num)
+        self.image_converter.PreAllocateConversion(self.input_format_obj, self.output_format_obj, self.width, self.height)
+        log.debug("pre-allocated ImageConverter to output {self.output_format_name}")
+
+    def init_binning_NOT_USED(self):
+        """
+        It's unclear how much use IPL.Binning would be...the docs aren't entirely
+        clear on whether this could vertically bin rows (70, 790) of Mono16,
+        given several parameters take a uint8. According to the uEye manual, this
+        seems more intended for Bayer filter, bin2x2 etc.
+
+        @see https://www.ids-imaging.us//manuals/ids-peak/ids-peak-ipl-documentation/2.15.0/en/classpeak_1_1ipl_1_1_binning.html
+        @see https://www.1stvision.com/cameras/IDS/IDS-manuals/uEye_Manual/hw_binning.html
+        """
+        # self.binning = IPL.Binning()
+        # binning.SetMode(IPL.Binning.BinningMode_Sum)
+        pass
+
+    def stop(self):
+        """ Called during shutdown.  """
+        if self.device is None:
+            return
+
+        if not self.taking_acquisition:
+            log.debug("stop: not running")
+            return
+
+        try:
+            log.debug("stop: stopping")
+            self.node_map.FindNode("AcquisitionStop").Execute()
+
+            self.datastream.StopAcquisition(IDSPeak.AcquisitionStopMode_Default)
+            # Discard all buffers from the acquisition engine
+            # They remain in the announced buffer pool
+            self.datastream.Flush(IDSPeak.DataStreamFlushMode_DiscardAll)
+            self.taking_acquisition = False
+
+            # Unlock parameters
+            self.node_map.FindNode("TLParamsLocked").SetValue(0)
+        except:
+            log.error(f"stop: caught exception", exc_info=1)
+        log.debug("stop: done")
+
+    def reset(self):
+        log.debug("resetting datastream")
+        if self.datastream is None:
+            log.error("no datastream to reset?!")
+            return
+
+        try:
+            # Check if buffers are already allocated
+            if self.datastream is not None:
+                # Remove buffers from the announced pool
+                for buffer in self.datastream.AnnouncedBuffers():
+                    self.datastream.RevokeBuffer(buffer)
+                self.buffers = []
+
+            payload_size = self.node_map.FindNode("PayloadSize").Value()
+            buffer_amount = self.datastream.NumBuffersAnnouncedMinRequired()
+
+            for _ in range(buffer_amount):
+                buffer = self.datastream.AllocAndAnnounceBuffer(payload_size)
+                self.buffers.append(buffer)
+
+            log.debug("reset: allocated buffers")
+        except:
+            log.error(f"reset: caught exception", exc_info=1)
+
+    ############################################################################
+    # Acquisition Loop (Software)
+    ############################################################################
+
+    def acquisition_loop(self):
+        """
+        This method is only used by the main() demonstrator. This is essentially
+        done by WrapperWorker in ENLIGHTEN.
+        """
+        while not self.shutdown_in_progress:
+            try:
+                if self.take_one_request is not None:
+                    self.send_trigger()
+                    self.get_spectrum()
+                    self.take_one_request = None
+            except:
+                log.error(f"acquisition_loop: caught exception", exc_info=1)
+                self.take_one_request = None
+
+    def send_trigger(self):
+        self.node_map.FindNode("TriggerSoftware").Execute()
+        self.node_map.FindNode("TriggerSoftware").WaitUntilDone()
+
+    def get_spectrum(self):
+        if self.datastream is None:
+            log.error("get_spectrum: no datastream?!")
+            return
+
+        timeout_ms = int(round(1000 + 2 * max(self.integration_time_ms, self.last_integration_time_ms)))
+        try:
+            buffer = self.datastream.WaitForFinishedBuffer(timeout_ms) # takes ms
+        except:
+            log.error(f"failed on datastream.WaitForFinishedBuffer({timeout_ms}ms)", exc_info=1)
+            return
+
+        # Get image from buffer (shallow copy)
+        image = EXT.BufferToImage(buffer)
+
+        if True:
+            # normal case, just vertically bin using the configured format
+            # (pass the buffer so it can be released after conversion)
+            spectrum = self.vertically_bin_image(image, buffer=buffer)
+        else:
+            # debug code to experimentally convert the same frame into every 
+            # supported format for comparison (assumes we're saving PNG or CSV)
+
+            # this will take awhile, so make a deep-copy and release the buffer
+            clone = image.Clone()
+            self.datastream.QueueBuffer(buffer)
+
+            for format_name in self.SUPPORTED_CONVERSIONS:
+                try:
+                    spectrum = self.vertically_bin_image(clone, format_name, save_csv=True, save_png=True)
+                except:
+                    log.error(f"exception during conversion to {format_name}", exc_info=1)
+
+        self.last_integration_time_ms = self.integration_time_ms
+        return spectrum
+
+    def vertically_bin_image(self, image, format_name=None, buffer=None, save_csv=False, save_png=False):
+        """ 
+        @note Stores a handle to a new AreaScanImage if the old one has expired.
+              This handle isn't "returned" but can be read by IDSDevice.
+        @returns a single vertically-binned spectrum
+        """
+        asi = None
+
+        if format_name is None:
+            format_name = self.output_format_name
+            format_obj = self.output_format_obj
+        else:
+            format_num = self.name_to_num[format_name]
+            format_obj = IPL.PixelFormat(format_num)
+
+        converted = self.image_converter.Convert(image, format_obj)
+
+        if buffer is not None:
+            # we were sent a Buffer, so release it immediately after conversion
+            self.datastream.QueueBuffer(buffer)
+            buffer = None
+
+        if converted is None:
+            log.error("vertically_bin_image: failed converting image to {format_name}")
+            return 
+
+        if self.rotate_180:
+            # would be nice if we could set this in the camera...
+            self.image_transformer.MirrorUpDownLeftRightInPlace(converted)
+
+        # this will hold the sum of all channels
+        spectrum = [0] * converted.Width()
+
+        # individual per-channel spectra for characterization
+        channel_count = format_obj.NumChannels()
+        # channel_spectra = [ [0] * converted.Width() for i in range(channel_count) ]
+
+        if self.output_format_name == "Mono16":
+            data = converted.get_numpy()
+            cropped = data[self.start_line:(self.stop_line + 1), :]
+            spectrum = np.sum(cropped, axis=0)   
+
+        else:
+            # we'd have to validate numpy process against different formats
+
+            try:
+                # iterate over each line of the 2D image
+                binned_count = 0
+                for row in range(converted.Height()):
+                    if self.start_line <= row <= self.stop_line:
+                        pixel_row = IPL.PixelRow(converted, row)
+                        binned_count += 1
+
+                        # iterate over each channel (R, G, B, a, etc)
+                        for channel_index, channel in enumerate(pixel_row.Channels()):
+                            # iterate over each pixel in the line (for this channel)
+                            values = channel.Values 
+                            for pixel, intensity in enumerate(values):
+                                spectrum[pixel] += intensity
+                                # channel_spectra[channel_index][pixel] += intensity
+                log.debug(f"binned {binned_count} lines from {self.start_line} to {self.stop_line}")
+            except:
+                log.error(f"vertically_bin_image: unable to vertically bin {format_name}", exc_info=1)
+                return
+
+        # save binned intensities (including per-channel breakdown) as CSV
+        
+        if save_csv:
+            pathname_csv = os.path.join(self.dir, f"{format_name}.csv")
+            with open(pathname_csv, "w") as outfile:
+                outfile.write("pixel, intensity, " + ", ".join(['chan_'+str(i) for i in range(channel_count)]) + "\n")
+                for pixel, intensity in enumerate(spectrum):
+                    outfile.write(f"{pixel}, {spectrum[pixel]}")
+                    for i in range(channel_count):
+                        outfile.write(f", {channel_spectra[i][pixel]}")
+                    outfile.write("\n")
+                log.debug(f"  saved {pathname_csv} ({channel_count} channels)")
+
+        # save converted image to PNG
+        if self.area_scan_enabled:
+            if self.last_asi_timestamp is None or (datetime.now() - self.last_asi_timestamp).total_seconds() >= self.area_scan_image_timeout_sec:
+                log.debug("time for a new AreaScanImage")
+                save_png = True
+            else:
+                log.debug("not yet time for a new AreaScanImage")
+            
+        # only generate a fresh AreaScanImage if the old one has expired
+        if save_png:
+            try:
+                # Now that we've completed vertical binning using the full-
+                # size image, we COULD reduce it in size and quality for the 
+                # visual area scan. Hyperspectral applications might prefer 
+                # high-quality, so make any downgrade/shrinkage optional.
+
+                height_orig = converted.Height()
+                width_orig = converted.Width()
+                if self.shrink_area_scan:
+                    factor = IPL.ScaleFactor()
+                    factor.x = 0.5
+                    factor.y = 0.5
+                    converted = converted.Scale(factor)
+
+                # 20% quality -- I don't know if this is doing anything or not?
+                png_param = IPL.ImageWriterPNGParameter()
+                if self.degrade_area_scan:
+                    png_param.Quality = 20
+
+                pathname_tmp = os.path.join(self.dir, f"{format_name}-tmp.png")
+                pathname_png = os.path.join(self.dir, f"{format_name}.png")
+                IPL.ImageWriter.WriteAsPNG(pathname_tmp, converted, png_param)
+                os.replace(pathname_tmp, pathname_png)
+                log.debug(f"saved {pathname_png}")
+
+                self.last_area_scan_image = AreaScanImage(
+                    pathname_png = pathname_png, 
+                    width        = converted.Width(), 
+                    height       = converted.Height(), 
+                    width_orig   = width_orig,
+                    height_orig  = height_orig, 
+                    format_name  = format_name)
+                log.debug(f"stored {self.last_area_scan_image}")
+                self.last_asi_timestamp = datetime.now()
+            except:
+                log.error(f"vertically_bin_image: unable to save {format_name} as PNG", exc_info=1)
+
+        return spectrum
+
+    ############################################################################
+    # Utility
+    ############################################################################
+
+    def next_name(self, path, ext):
+        num = 0
+
+        def build_string():
+            return f"{path}_{num}{ext}"
+
+        while os.path.exists(build_string()):
+            num += 1
+        return build_string()
+
+    def dump_node(self, name=None, node=None, indent="  "):
+        if name is None and node is None:
+            log.error("must be called with node or name")
+            return
+            
+        type_ = "UNKNOWN"
+        try:
+            if node is None:
+                node = self.node_map.FindNode(name)
+                if node is None:
+                    log.error(f"'{name}' not found in node_map")
+                    return
+
+            if name is None:
+                name = node.Name()
+
+            type_ = IDSPeak.NodeTypeEnumEntryToString(node.Type())
+            value = None
+
+            if   not node.IsAvailable():                         value = "NOT AVAILABLE"
+            elif not node.IsImplemented():                       value = "NOT IMPLEMENTED"
+            elif     node.IsDeprecated():                        value = "DEPRECATED"
+            elif isinstance(node, IDSPeak.FloatNode):            value = f"{node.Value()} {node.Unit()}"
+            elif isinstance(node, IDSPeak.StringNode):           value = node.Value()
+            elif isinstance(node, IDSPeak.BooleanNode):          value = node.Value()
+            elif isinstance(node, IDSPeak.IntegerNode):          value = f"{node.Value()} {node.Unit()}"
+            elif isinstance(node, IDSPeak.RegisterNode):         value = f"0x{node.Address():08x} (len {node.Length()})"
+            elif isinstance(node, IDSPeak.EnumerationEntryNode): value = node.SymbolicValue() 
+            elif isinstance(node, IDSPeak.CommandNode):          value = None
+            elif isinstance(node, IDSPeak.CategoryNode):
+                log.debug(f"{indent}{name} ({type_}) = ")
+                indent += "  "
+                for subnode in node.SubNodes():
+                    self.dump_node(node=subnode, indent=indent)
+                return
+            elif isinstance(node, IDSPeak.EnumerationNode):
+                value = node.CurrentEntry().SymbolicValue()
+                if len(node.AvailableEntries()) > 1:
+                    value += " (" + ", ".join([ e.SymbolicValue() for e in node.AvailableEntries() ]) + ")" 
+            else:
+                log.error(f"{indent}{name} is unknown type {type_}")
+
+            if not node.IsWriteable():
+                value = str(value) + " (READ-ONLY)"
+
+            if value is None:
+                log.debug(f"{indent}{name} ({type_})")
+            else:
+                log.debug(f"{indent}{name} ({type_}) = {value}")
+        except Exception as ex:
+            log.error(f"{indent}{type_} {name}: {ex}")
+            pass
+
+if __name__ == '__main__':
+    """ invoke from Wasatch.PY folder as: python -u wasatch/IDSCamera.py """
+
+    from wasatch import applog
+    logger = applog.MainLogger("DEBUG")
+
+    log.debug("getting IDSPeak.DeviceManager instance")
+    camera = None
+    use_threading = False
+
+    try:
+        log.info("main: instantiating Camera")
+        camera = IDSCamera()
+
+        log.info("main: calling camera.connect")
+        if not camera.connect():
+            log.critical("No IDS camera found")
+            sys.exit(1)
+
+        log.info("main: starting camera acquisition")
+        camera.start()
+
+        if use_threading:
+            log.info("main: spawning acquisition loop")
+            thread = threading.Thread(target=camera.acquisition_loop, args=())
+            thread.start()
+
+        log.info("main: monitoring acquisitions")
+        try:
+            # break loop with ctrl-C
+            while True:
+
+                if use_threading:
+                    log.info("main: dropping request into acquisition loop")
+                    camera.take_one_request = object()
+                    while camera.take_one_request is not None:
+                        time.sleep(0.01)
+                        pass
+                else:
+                    log.info("main: taking spectrum")
+                    camera.send_trigger()
+                    camera.get_spectrum()
+
+                log.info("main: measurement completed, sleeping 5sec")
+                # time.sleep(5)
+                break
+
+        except:
+            log.error("main: exception during measuremnet loop", exc_info=1)
+        finally:
+            # make sure to always stop the acquisition_thread, otherwise
+            # we'd hang, e.g. on KeyboardInterrupt
+            log.info("main: shutting down (joining thread)")
+            camera.shutdown_in_progress= True
+            if use_threading:
+                thread.join()
+
+    except KeyboardInterrupt:
+        log.critical("User interrupt: Exiting...")
+    except:
+        log.error(f"Exception (main)", exc_info=1)
+    finally:
+        # Close camera and library after program ends
+        if camera is not None:
+            log.info("main: closing camera")
+            camera.close()
+        log.info("main: closing Library")
+        IDSPeak.Library.Close()