Needed Functions: - Consistent 'CM_GetCameraType' and 'CM_GetCameraConfigurationName' - 'CM_CAMTAG_Config_GetCountsPerPrimary' functions that take camera rather than tags, and a function to remove calibration. Overview: Objects - CameraManager - Maintains list of cameras and the current camera. - Camera - Controls the physical camera - CameraAcquisitionParameters - Specifies the parameters needed to generate an image from reads of the CCD. ( May be result of multiple reads if frames are summed or auto-exposure is turned on ). - CameraMode - Describes one of the configured camera modes for a camera. A camera mode is currently just a bank of parameters ( typically including 'View:Search', 'View:Focus' and 'Acquire:Record' ) that can appear in the camera interface. There is no fundamental reason that two camera modes need to have fundamentally differing parameters. The only current use for multiple modes is for the US1000FT camera to provide a bank of parameters that use the read mode corresponding to frame transfer readout. CameraManager: Object CM_GetCameraManager(); - Returns the camera manager object. Object CM_GetCameras( Object cam_mgr ); - Returns an 'ObjectList' object containing a list of the available cameras. void CM_SelectCamera( Object cam_mgr, Object camera ); - Sets the specified camera as the currently selected camera. Object CM_GetCurrentCamera(); - Returns the currently selected camera. Camera: Coordinates: There are two main coordinate systems used when specifying readout area on a CCD, raw coordinates and binned coordinates. Raw coordinates for a CCD map the accessible active area of the CCD and are not affected by camera orientation, binning, or readout transposition. The coordinates are the effective CCD pixels with values in [0,ccd_width-1]x[0,ccd_height-1], where the effective active area of the CCD has size (ccd_width,ccd_height). An effective CCD pixel is the smallest grouping of CCD pixels distinguishable via the controller. Binned coordinates for a given set of acquisition parameters are affected by the default camera orientation and the binning and transpose in the acquisition parameters. The coordinates are determined by the largest image that can be read by enlarging the raw CCD coordinates of the acquisition parameters, but leaving all other settings constant. This is the coordinate system used when specifying read area in old-style 'SSC*Acquire' commands. Note if a CCD dimension is not divisible by the binning in that dimension, then there is some ambiguity about which CCD pixels make up each binned pixel: for ccd size (ccd_width,ccd_height) and binning '(bin_x,bin_y)', binned pixel (0,0) can have any CCD pixel in the range [0,mod(ccd_width,bin_x))x[0,mod(ccd_height,bin_y)) as its top-left pixel. When setting the read area of a set of acquisition parameters in terms of binned pixels, the ambiguity is resolved using the alignment of the top-left binned pixel in the current read area in CCD coordinates. Camera orientation and image transpositions are described by a number which encodes a transformation generated by 90 degree rotations and reflectsions. The number consists of three flags at bits '0', '1', and '8', where 0 - horizontal flip 1 - vertical flip 8 - diagonal flip with any diagonal flip performed after any horizontal or vertical flip. In terms of rotation followed by a horizontal flip, the values represent 0 - no rotation , no flip 1 - no rotation , horizontal flip 2 - rotate right by 180, horizontal flip 3 - rotate right by 180, no flip 256 - rotate right by 90 , horizontal flip 257 - rotate right by 270, no flip 258 - rotate right by 90 , no flip 259 - rotate right by 270, horizontal flip General: String CM_GetCameraName( Object camera ); void CM_SetCameraName( Object camera, String new_camera_name ); - Gets/Sets the user name associated with the camera. If the string is not empty, this name is used in menus and dialogs to designate the camera. If it is empty, the camera identifier is used instead. String CM_GetCameraControllerClass( Object camera ); - Returns a string describing the electronics/driver combination controlling the camera. The current possible values are "FirstLight" "MSC" "PICM" "FAUX" String CM_GetCameraIdentifier( Object camera ); - Returns a unique string identifying the camera. It typically contains a string identifying the camera configuration followed by the index of the camera in the list of configured cameras. CCD: void CM_CCD_GetSize( Object camera, Number &ccd_width, Number &ccd_height ); - Sets into '(ccd_width,ccd_height)' the size in effective CCD pixels of the active area of the CCD. This is not affected by the default camera orientation. void CM_CCD_GetPixelSize_um( Object camera, Number &pix_width, Number &pix_height ); - Sets into '(pix_width,pix_height)' the size of a CCD pixel in microns ( Note: this is not the active area of the pixel, but the distance between the top-left corners of adjacent pixels ). This is not affected by the default camera orientation. void CM_CCD_CalcActiveSize( Object camera, Object acq_params, Number &ccd_width, Number &ccd_height ); - Returns in '(ccd_width,ccd_height)' the size in pixels of the active area of the CCD when read out using 'acq_params', or the active area of the entire CCD if 'acq_params' is 'NULL'. The active area may be affected by acquisition parameters like 'Read Mode'. String CM_CCD_GetDefectDescriptor( Object self ) void CM_CCD_SetDefectDescriptor( Object self, String defects ) - Get/Set String describing CCD defects. A defect string consists of a comma-separated list of primitive defect specifiers. Each primitive defect specifier has the form where '' can be one of the following ( all coordinates are in raw CCD coordinates ). n - specifies row or column 'n' n-m - specifies the set of rows or columns in the range '[n,m]' [t,l,b,r] - specifies the set of CCD pixels in the range [l,r)x[t,b) ( note that column 'r' and row 'b' are excluded ). '' is a sequence of zero or more of the following characters. c,C - Specifies that correction is to be done horizontally across the specified region. If the region is specified as 'n' or 'n-m', then this also indicates the the numbers specify columns. r,R - Specifies that correction is to be done vertically across the specified region. If the region is specified as 'n' or 'n-m', then this also indicates the the numbers specify rows. s,S - Indicates that the correction linearly interpolates across the defect region. m,M - Indicates that the correction at each defect point is the mean - of the two bounding good pixels in the specified direction. If both 'c' and 'r' are specified, the correction at each pixel is the mean of the horizontal and vertical corrections. If neither 's' or 'm' is specified, interpolation is assumed. If 'c' and 'r' are omitted, defects specified by 'n' and 'n-m' are assumed to represent columns and, defects specified by '[t,l,b,r]' both 'c' and 'r' are assumed. For both interpolation and mean, if one edge of the defect region is at the edge of the CCD, the correction value is simply copied from the bound specifying a valid pixel, or '0' if the defect spans the CCD in the direction of the correction. Orientation: The camera orientation is specified in the camera by a default transpose. By default, after an acquisition the resulting image is transposed by the default transpose before being placed in the destination image. Number CM_Config_GetDefaultTranspose( Object camera ); void CM_Config_SetDefaultTranspose( Object camera, Number trans ); - Get/Set the default transpose void CM_CalcFrameSize( Object camera, Number transpose, Number adj_x, Number adj_y, Number bin_x, Number bin_y, Number &dst_width_out, Number &dst_height_out ); - Calculate the largest image '(dst_width_out,dst_height_out)' that can be acquired from 'camera' with binning '(bin_x,bin_y)', transpose 'transpose' applied in addition to the default camera orientation, and binned pixels aligned with CCD pixel '(adj_x,adj_y)'. Shutters: A shutter is a physical output from the controller that can be used to control illumination falling on to the CCD. ( Note that this excludes 'Electrical shutters' as used on the Matscan, which is instead a CCD control mechanism that rapidly drains the CCD while it is being exposed ). A camera can support any number of shutters ( current controllers support from 0 to 2 shutters ), with shutters being considered distinct if one may be closed while the others remain open. If a camera supports 'n' shutters, a consisting of bits 'b_...b_0' ( i.e. a number in the range [0,2^n-1], with shutter '0' specified by the least significant bit ) can be used to specify an arbitrary subset of the shutters. Current configurations and their shutter support are MSC - The MSC controller contains two shutter outputs at the back of the controller, each of which may be attached to a beam blanker on the microscope or a lens on the Filter to deflect the beam from the CCD. Only one of these outputs can be asserted closed at any point in time. FirstLight - The FirstLight controller contains two shutter outputs like the MSC, but they can be controlled independently ( neither, either, or both may be closed ) PICM - These controllers technically has multiple shutter outputs, but they can not be independently controlled so the software just considers it one shutter. The current configurations are DV 300W - Uses mechanical shutter controlled over same cable that controls CCD Enfina - Uses shutter connected from output on back of controller to filter. If a Number CM_CountShutters( Object camera ); - Returns the number of shutters available for controlling exposure of the CCD during readout. Number CM_GetFrameShuttersMask( Object self ); - Returns a shutter mask specifying which shutters can be controlled during a readout Number CM_GetConfigurableIdleShuttersMask( Object self ) - Returns a shutter mask specifying which shutters can have their idle state specified Number CM_GetConfigurableCurrentShuttersMask( Object self ) - Returns a shutter mask specifying which shutters can have their current state specified The following are only available for cameras with controller class "MSC" or "FirstLight" void CM_GetIdleShutterState( Object camera, Number shutter_index, Number &is_closed ); void CM_SetIdleShutterState( Object camera, Number shutter_index, Number is_closed ); - Get/Set whether the shutter specified by 'shutter_index' should be opened or closed when the camera is not reading out. Note that the shutters might not be independently controllable, in which case closing one might implicitly open the other. void CM_SetCurrentShutterState( Object camera, Number shutter_index, Number is_closed ); - If outside a readout, specify whether the shutter specified by 'shutter_index' is open or closed. If within a readout, the behavior is camera-specific, but whatever happens the state will be replaced by the idle state at the end of the readout. Number CM_GetIdleCameraState_ShutterStates( Object self, Number shut_sel, Number &des_shut_state ); Number CM_SetIdleCameraState_ShutterStates( Object self, Number shut_sel, Number des_shut_state ); - Get or set the idle state of the specified shutters. 'shut_sel' specifies a shutter mask specifying which shutters will be queried/adjusted, and 'des_shut_state' is a shutter mask whose bits ( at locations specified by '1's in 'shut_sel ) specify the state of the corresponding shutter, where '1' indicates that the shutter is closed. Return 'true' if it the operation can be ( and was ) performed for the camera. Possible reasons for failure are that the camera does not support any shutter specified in 'shut_sel', or the camera does not support idle shutter states. Number CM_GetCurrentCameraState_ShutterStates( Object self, Number shut_sel, Number &des_shut_state ); Number CM_SetCurrentCameraState_ShutterStates( Object self, Number shut_sel, Number des_shut_state ); - Get or set teh current state of the specified shutters. The arguments and return value are the same as 'CM_{Get|Set}IdleCameraState_ShutterStates' Insert/Retract: Number CM_IsCameraRetractable( Object camera ); Number CM_GetCameraInserted( Object camera ); void CM_SetCameraInserted( Object camera, Number inserted ); void CM_Config_GetInsertabilityDelays( Object camera, Number &insert_delay, Number &retract_delay ); void CM_Config_SetInsertabilityDelays( Object camera, Number insert_delay, Number retract_delay ); - insertibility delays specify the times in seconds from the start of insertion to when a good image can be acquired ( 'insert_delay' ) and the time from the start of retraction to when the camera no longer blocks the beam ( 'retract_delay' ). Number CM_CAMTAG_Config_GetIsInsertable( TagGroup cam_config_tags, Number &is_retractable ); Number CM_CAMTAG_Config_SetIsInsertable( TagGroup cam_config_tags, Number is_retractable ); - Enables or disables the insertion function for insertable cameras; existence of this tag also triggers the appearance of an "Is Insertable" checkbox option in the "Insertion" configuration UI. High-level state parameters Number CM_SupportsNamedStateParameter( Object camera, String state_val_name ) - Returns support flag for static (configure-once) camera parameters. Named state parameters include: is_inserted - Whether the camera is insertable. This is the camera's native capability; it can be overriden by CM_CAMTAG_Config_SetIsInsertable. ccd_temperature_setpoint_c - camera temperature set point shutter_state is_ccd_temperature_control_on High-level acquisition parameters Number CM_SupportsNamedHighLevelAcquisitionParameter( Object camera, String named_param ) - Returns 'true' if the camera supports the high level parameter 'named_param', 'false' otherwise. This only returns 'true' if the named parameter is actually configurable. I.e. if a camera always does antiblooming or never does antiblooming, 'do_antiblooming' returns 'false'. It will only return true if whether a readout is done with antiblooming is configurable. Named high level parameters include exposure_s - Exposure time in seconds binning read_area - Rectangle within the active area of the CCD that is to be read out. do_antiblooming - Whether the readout does antiblooming. num_frame_shutters - The number of shutters that are opened and closed during a redout. This parameter is only supported if the number of shutters can be independently specified ( i.e. it is not solely dependent on other high level parameters ). primary_shutter_pre_exposure_compensation_s - Number of seconds between the time the primary shutter opens and clearing the CCD stops before exposing. This was called 'settling' in old versions of the camera plugin. primary_shutter_post_exposure_compensation_s - Number of seconds between the time the primary shutter closes after exposre and readout starts. secondary_shutter_pre_exposure_compensation_s - Number of seconds between the time the secondary shutter opens and clearing the CCD stops before exposing. secondary_shutter_post_exposure_compensation_s - Number of seconds between the time the secondary shutter closes after exposre and readout starts. Antiblooming: Number CM_CanSetAntiblooming( Object camera ); - Returns 'true' if antiblooming can be turned on/off. Read Modes: Number CM_CountReadModes( Object camera ); - Returns the number of read modes supported by this camera. Number CM_GetReadModeForNamedAcquisitionStyle( Object camera, String acq_style ) - Returns the index of the read mode that this camera associates with a read style characterized by the string 'acq_style'. If the string is not recognized, the default read mode, '0', is returned. The acquisition style names that are currently recognized are ( case is important ) max_view - Returns the read mode that reads out the maximal active area on the CCD. fast_video - Returns a read mode that will read out as fast as possible ( the actual area read can be comprimized ) spectroscopy - Returns the read mode that should be used for spectroscopy acquisitions ( where the CCD is centered in the parallel direction on the CCD ). Quality: Number CM_CountQualityLevels( Object camera, Object acq_params ) - Returns the number of quality levels supported by the camera. Temperature: Currently, there are two levels of software control of temperature: none and full. Full control basically means the camera supports reading the current temperature, specifying a set point temperature, and checking whether the temperature has stabilized at the set point ( currently only cameras with controller class "PICM" support this ). On top of this are implemented 'startup', 'shutdown' and 'target' temperatures. While the camera is active, if a 'target' temperature is set, the camera temperature is brought to the target temperature in the background at a maximum rate specified by the maximum temperature change rate. The 'startup' temperature if specified is used as the initial target temperature, and the 'shutdown' temperature is made the set point of the camera when the camera is deactivated. Number CM_DoesCameraNeedToBeCooled( Object camera ); - Returns 'true' if camera can be cooled ( equivalent to old 'MSCHasFeature(3)' ). Basically 'true' for everything but 'Bioscan'. Number CM_HasTemperatureControl( Object camera ); - Returns 'true' if temperature can be queried and controlled via software. Number CM_GetTemperatureResolution_C( Object camera ); Number CM_GetMinimumTemperature_C( object camera ); Number CM_GetMaximumTemperature_C( Object camera ); Number CM_GetActualTemperature_C( Object camera ); - Return the measured temperature of the CCD void CM_SetTargetTemperature_C( Object camera, Number use_target_temp, Number temp_C ); Number CM_GetTargetTemperature_C( Object camera, Number &temp_C ); - For 'Set', set the target temperature to 'temp_C', and set whether to actually use the temperature as a target to 'use_target_temp'. For 'Get', put the target temperature in 'temp_C', and return whether 'temp_C' is actually to be used as a target. void CM_SetStartupTemperature_C( Object camera, Number use_startup_temp, Number temp_C ); Number CM_GetStartupTemperature_C( Object camera, Number &temp_C ); void CM_SetShutdownTemperature_C( Object camera, Number use_shutdown_temp, Number temp_C ); Number CM_GetShutdownTemperature_C( Object camera, Number &temp_C ); - Similar to 'CM_{Get|Set}TargetTemperature_C' for startup and shutdown temperatures respectively. Number CM_GetLocalTargetTemperature_C( Object camera, Number &temp_C ); - If the hardware is currently trying to attain a set point temperature, return 'true' and set 'temp_C' to that temperature. ( Note, this is not necessarily the target temperature, but more likely a nearby temperature goal in the direction of the target ). Number CM_IsTemperatureStable( Object camera, Number &targ_temp_C ); - Return whether the CCD temperature has stabilized the target temperature if one is specified, or stabilized at all if one is not specified. Set 'targ_temp_C' to the target temperature if one is specified, or the current set point in the hardware if it is not. Number CM_GetTemperatureMaxChangeRate( Object camera ); void CM_SetTemperatureMaxChangeRate( Object camera, Number maxTempChange ); Location: The camera location specifies where the camera is located with respect to its environment. The location is not interpreted by the camera, and only has two properties used by the camera, 'Identifier' and 'Name'. The 'Identifier' is a string that uniquely locates a camera in its environment that is fixed across installations and versions, while the 'Name' is the string that is associated with the location in the UI ( and as such might potentially be localized or differ between configurations ). If a client needs to specify a location in a manner that will work across all installations, it should use the 'Identifier'. The currently available location identifiers are unspecified - The location has not yet been configured. wide_angle - The camera is in the wide angle port. high_resolution - The camera is in the high resolution port. filter - The camera is at the end of a external filter. ( If it is at the end of an in-column filter, the location is 'high_resolution' ). none - The camera is not at any known location ( e.g. it is sitting on a desk ) String CM_Config_GetLocationIdentifier( Camera camera ) - Returns the identifier of the location at which the camera is installed. void CM_Config_SetLocationIdentifier( Camera camera, String cam_loc_ident ) - Specifies that the camera is installed at the location with the identifier 'cam_loc_ident'. String CM_Config_GetLocationName( Camera camera ) - Returns the name of the location at which the camera is installed. ShutterSite: A shutter site specifies where a shutter out signal on a camera controller is connected. Similar to camera location above, the camera for the most part does not interpret this site, and only uses two of its properties, 'Identifier' and 'Name'. The 'Identifier' is a string that uniquely locates a shutter site on a microscope that is fixed across installations and versions. The 'Name' is a user friendly string naming the shutter site that appears in UI elements ( and as such it might be localized or differ between configurations ). If a client needs to specify a shutter site in a manner that will work across all installations, it should use the 'Identifier'. The currently available shutter site identifiers are unspecified - The shutter site has not been specified for the shutter. pre_specimen - The shutter is the pre-specimen shutter. post_specimen - The shutter is the post-specimen shutter. filter - The shutter is in the filter. none - The shutter is not connected. unknown - The shutter is connected, but not to a known site. String CM_Config_GetShutterSiteIdentifier( Camera camera, uint32 shut_idx ) - Return the identifier of the site at which the shutter at index 'shut_idx' is connected. void CM_Config_SetShutterSiteIdentifier( Camera camera, uint32 shut_idx, String shut_site_ident ) - Specify that the shutter at index 'shut_idx' is connected to the shutter site with identifier 'shut_site_ident'. CameraMode: Number CM_CountCameraModes( Object cam_mgr, Object camera ); - Returns the number of camera modes configured in the camera manager for the specified camera. Number CM_GetCurrentCameraModeIndex( Object cam_mgr, Object camera ); - Returns the index of the current camera mode in the camera manager. This is the mode that determines which parameters appear in the 'Camera View' and 'Camera Acquire' palettes. Object CM_GetCameraModeByIndex( Object cam_mgr, Object camera, Number idx ); - Returns a camera mode object describing the mode at the specified index. Object CM_GetCurrentCameraMode( Object cam_mgr, Object camera ); - Returns CM_GetCameraModeByIndex( cam_mgr, camera, CM_GetCurrentCameraModeIndex( cam_mgr, camera ) ); void CM_SetCurrentCameraModeByIndex( Object cam_mgr, Object camera, Number new_cam_mode_idx ); - Sets the current camera mode in the camera manager to the mode at the specified index. CameraAcquisitionParameters: Creation/Persistence: The following functions are used to create a base camera acquisition parameter set. The parameters specify an unprocessed ( except for defect correction ), unbinned read of the entire CCD with exposure '1.0' seconds. Most of the remainaing parameters in effect are copied from the 'Record' parameter set, except that all extra processing ( including auto-exposure and frame summing ) is turned off. The only exceptions are that the functions containing 'View' are set to prefer continuous readout, and if the camera has a range of readout qualities the 'Low', 'Medium', and 'High' specify a level. Object CM_GetCameraAcquisitionParameterSet_LowQualityImagingView( Object camera ); Object CM_GetCameraAcquisitionParameterSet_MediumQualityImagingView( Object camera ); Object CM_GetCameraAcquisitionParameterSet_HighQualityImagingView( Object camera ); Object CM_GetCameraAcquisitionParameterSet_LowQualityImagingAcquire( Object camera ); Object CM_GetCameraAcquisitionParameterSet_MediumQualityImagingAcquire( Object camera ); Object CM_GetCameraAcquisitionParameterSet_HighQualityImagingAcquire( Object camera ); Object CM_CreateAcquisitionParameters( Object camera, Number processing, Number exposure, Number binX, Number binY ,Number ccdT ,Number ccdL ,Number ccdB ,Number ccdR ); Object CM_CreateAcquisitionParameters_FullCCD( Object camera, Number processing, Number exposure, Number binning_x, Number binning_y ); - Create a camera acquisition parameters set based on 'CM_GetCameraAcquisitionParameterSet', but with the specified exposure, binning, and processing. The following functions are for manipulating the standard, persisted camera acquisition parameters, currently just 'Search', 'Focus', and 'Record'. In general, persistent parameter sets can be created using the first function by specifying a mode name, style name, and parameter set name. Parameter sets so created are linked to a location in the global tags, so calling 'CM_LoadCameraAcquisitionParameterSet' will initialize the parameter set with settings from tags, and 'CM_SaveCameraAcquisitionParameterSet' will save the parameter set to tags. Parameter sets created by other means are not linked to a tag location and will fail if either of those functions are called. To create a parameter set linked to one of the standard persisted sets, use the following mode_name style_name param_set_name Search "Imaging" "View" "Search" Focus "Imaging" "View" "Focus" Record "Imaging" "Acquire" "Record" Object CM_GetCameraAcquisitionParameterSet( Object camera, String mode_name, String style_name, String param_set_name, Number do_create ); - Get a parameter set initialized from the tags associated with the specified 'mode_name', 'style_name', and 'param_set_name' if the tags exist. If the tags do not exist, return 'NULL' if 'do_create' is false, otherwise create a parameter set linked to the appropriate tag path. ( Note that if the parameter set is created, the contents are not saved to tags until 'CM_SaveCameraAcquisitionParameters' is called on the object ). void CM_LoadCameraAcquisitionParameterSet( Object camera, Object acq_params ); void CM_SaveCameraAcquisitionParameterSet( Object camera, Object acq_params ); - Loads/Saves 'acq_params' from/to the linked persistent parameters. Acquisition Parameters: Common Readout Parameters Number CM_GetReadMode( Object acq_params ); void CM_SetReadMode( Object acq_params, Number read_mode ); - Get/Set the readout mode to use. The number is an index between '0' and 'camera.CM_CountReadModes()' A read mode specifies one of the allowable ways of reading out the CCD, such as full frame, frame transfer, or interline. The 'read_mode' is an index, with '0' specifying the default read mode. ( Thus, for a camera supporting only full frame readout, index '0' specifies full frame readout, while for a camera supporting only interline readout, '0' specifies interline readout ). The read mode may affect the set of pixels on the CCD that are considered active ( e.g. for frame transfer readout, the masked half is considered part of the inactive region ). Number CM_GetExposure( Object acq_params ); void CM_SetExposure( Object acq_params, Number exposure ); - Get/Set the exposure, specified in seconds. void CM_GetBinning( Object acq_params, Number &bin_x, Number &bin_y ); void CM_SetBinning( Object acq_params, Number bin_x, Number bin_y ); - Get/Set the binning void CM_GetCCDReadArea( Object acq_params, Number &top, Number &left, Number &bottom, Number &right ); void CM_SetCCDReadArea( Object acq_params, Number top, Number left, Number bottom, Number right ); - Get/Set the read area in raw CCD coordinates void CM_GetBinnedReadArea( Object camera, Object acq_params, Number &bin_area_t, Number &bin_area_l, Number &bin_area_b, Number &bin_area_r ); void CM_SetBinnedReadArea( Object camera, Object acq_params, Number bin_area_t, Number bin_area_l, Number bin_area_b, Number bin_area_r ); - Get/Set the read area in binned CCD coordinates void CM_SetProcessing( Object acq_params, Number processing ); Number CM_GetProcessing( Object acq_params ); - Get/Set part of the corrections. Possible values are 1 - No dark or gain correction 2 - Dark correction only 3 - Dark and gain correction. Number CM_GetCorrections( Object acq_params, Number corr_mask ); void CM_SetCorrections( Object acq_params, Number corr_mask, Number corrections ); - Turn on and off corrections individually. The corrections are specified by a bitfield 'corrections', and 'corr_mask' specify which corrections are to be returned or modified. The possible correction bits are 0 - defect correction 4 - bias correction 5 - quadrant correction 8 - dark correction 9 - gain correction ( Currently, if specified, dark correction must be specified too ). Number CM_GetDoContinuousReadout( Object acq_params ); void CM_SetDoContinuousReadout( Object acq_params, Number dcr ); - Get/Set whether the readout should be optimized for continuous acquisition. void CM_SetStandardParameters( Object acq_params\ , Number processing, Number exposure\ , Number bin_x, Number bin_y\ , Number ccd_area_t, Number ccd_area_l, Number ccd_area_b, Number ccd_area_r ); - Set the specified processing, exposure, binning, and ccd read area. The binning does not take into account the camera orientation, and the read area is in raw CCD coordinates. void CM_SetStandardParameters_Dst( Object camera, Object acq_params\ , Number processing, Number exposure\ , Number bin_x_dst, Number bin_y_dst\ , Number bin_area_t, Number bin_area_l, Number bin_area_b, Number bin_area_r ); - Set the specified processing, exposure, binning, and binned read area. The binning takes into account the camera orientation and any transpose set in 'acq_params' ( i.e. a diagonal flip in the composed transpose means that 'bin_x_dst' is in the vertical direction in raw CCD coordinates ), and the read area is in binned CCD coordinates. Thus, the parameters have the same meaning as the corresponding ones in the old 'SSC*Read' commands. Antiblooming: Number CM_GetDoAntiblooming( Object acq_params ); void CM_SetDoAntiblooming( Object acq_params, Number do_antiblooming ); - Get/Set whether to do antiblooming. Shutter Related Readout Parameters Number CM_GetShutterExposure( Object acq_params ); void CM_SetShutterExposure( Object acq_params, Number do_shutter_exposure ); - Get/Set whether the shutter should be closed during exposure. Note that simply closing the shutter during exposure for an acquisition might not create a good dark reference. ( e.g. for the enfina, the shutter must be closed, then the dark reference acquired after a delay ). void CM_GetChooseNumFrameShuttersAutomatically( Object acq_params, Number &choose ) void CM_SetChooseNumFrameShuttersAutomatically( Object acq_params, Number choose ) - Get/Set whether the number of frame shutters should be chosen automatically, or if the number should be configured manually. This is only used if the number of shutters can be configured. void CM_GetNumFrameShutters( Object acq_params, Number &num_shut ) void CM_SetNumFrameShutters( Object acq_params, Number num_shut ) - Get/Set the number of frame shutters to open/close during a readout. void CM_GetPrimaryFrameShutterIndex( Object acq_params, Number &index ) void CM_SetPrimaryFrameShutterIndex( Object acq_params, Number index ) - Specifies which shutter is the 'primary' shutter for the readout. If the number of shutters is '0', the primary shutter is the one that is closed for dark acquisitions. If the number of shutters is '1', the primary shutter is the one that is closed during clearing and readout, but open during exposure. If the number of shutters is '2', the 'primary' shutter is fundamentally arbitrary, but usually it is physically the shutter that is closer to the camera ( e.g. the post-specimen or filter shutter ), and is the one that opens last and closes first ( and the secondary shutter is the pre-specimen shutter ). Number CM_GetShutterClosedBetweenFrames( Object acq_params ); void CM_SetShutterClosedBetweenFrames( Object acq_params, Number is_closed ); - Specify whether the shutter used for readout is to be opened or closed during any delay between frames of a continuous readout. ( Only available on "MSC", equivalent to the 'Normally Closed' acquisition parameter setting ). void CM_GetPrimaryShutterPreExposureCompensation_s( Object acq_params, Number &exp_comp_s ) void CM_SetPrimaryShutterPreExposureCompensation_s( Object acq_params, Number exp_comp_s ) - Get/Set the delay in seconds between the time the primary shutter is opened before exposure, and the time the CCD stops clearing. void CM_GetPrimaryShutterPostExposureCompensation_s( Object acq_params, Number &exp_comp_s ) void CM_SetPrimaryShutterPostExposureCompensation_s( Object acq_params, Number exp_comp_s ) - Get/Set the delay in seconds between the time the primary shutter is closed after exposure, and the time the CCD begins readout. void CM_GetSecondaryShutterPreExposureCompensation_s( Object acq_params, Number &exp_comp_s ) void CM_SetSecondaryShutterPreExposureCompensation_s( Object acq_params, Number exp_comp_s ) - Get/Set the delay in seconds between the time the secondary shutter is opened before exposure, and the time the CCD stops clearing. void CM_GetSecondaryShutterPostExposureCompensation_s( Object acq_params, Number &exp_comp_s ) void CM_SetSecondaryShutterPostExposureCompensation_s( Object acq_params, Number exp_comp_s ) - Get/Set the delay in seconds between the time the secondary shutter is closed after exposure, and the time the CCD begins readout. Quality/Speed Number CM_GetQualityLevel( Object acq_params ); void CM_SetQualityLevel( Object acq_params, Number level ) - Sets the quality level Extra processing Number CM_GetAcqTranspose( Object acq_params ) void CM_SetAcqTranspose( Object acq_params, Number transform ) - Transform applied to an image in addition to that induced by the camera orientation. void CM_SetNumberToSum( Object acq_params, Number num ); Number CM_GetNumberToSum( Object acq_params ); - Specify that resulting image is from sum of 'num' images from the camera. void CM_SetAutoExpose( Object camera, Object acq_params, Number has_auto_expose, number do_auto_expose ); - Turn auto-exposure on or off based on value of 'do_auto_expose. ( 'has_auto_expose' should be 'true' ) number CM_IsAutoExposeOn( Object camera, Object acq_params ); - Returns whether auto-exposure is turned on for 'acq_params' Acquisition: Given a 'camera' and an arbitrary set of acquisition parameters 'acq_params', 'CM_Validate_AcquisitionParameters' can be used to ensure that the parameters have appropriate settings, and 'CM_CameraCalcImageForm' can be used to determine an appropriate size and data type. 'CM_AcquireImage' can be used to acquire a single image as specified by 'acq_params'. Number CM_Validate_AcquisitionParameters( Object camera, Object acq_params ); - If 'camera' can acquire an image as specified by 'acq_params', do nothing. Otherwise, modifiy 'acq_params' so it specifies a valid readout from 'camera'. The validation tries to change as little as possible, preferring changing the read area to changing the binning. If there is no reasonable way to change an invalid parameter to a valid one ( extremely unlikely ), it throws an exception. Returns 'true' if any of the parameters were changed, 'false' otherwise. Number CM_IsValid_AcquisitionParameters( Object camera, Object acq_params ); - Return 'true' if 'camera' can acquire in image as specified by 'acq_params', 'false' otherwise. Number CM_PrepareCameraForAcquire( Object cam_mgr, Object camera, Object acq_params, Object user_interact, Number &wait_for_prepare ); - Does whatever is necessary to prepare the camera environment and camera for acquisition using the acquisition parameters 'acq_params'. If 'user_interact' is 'true', the user may be prompted before performing some actions, and if 'false' a default choice is made for those actions. If anything was changed when preparing the camera, 'true' is returned, otherwise 'false' is returned. The 'wait_for_prepare' variable is filled with an estimate in seconds of how long until the system settles ( e.g. the camera or mask finishes inserting or retracting ). Currently, only the following are done: - If the camera is retractable, it is inserted. Each retractable camera is retracted. The user will be prompted for this if user interaction is allowed, else this is done by default. - For US1000 frame transfer cameras, the CCD mask is inserted or retracted as required by 'acq_params'. void CM_CameraCalcImageForm( Object camera, Object acq_params, Number &data_type, Number &width, Number &height ); - Set 'data_type' to a type of an image that can hold the values produced by a readout from 'camera' using parameters 'acq_params', and set '(width,height)' to the appropriate size of the image. Image NewImage( String title, Number data_type, Number width, Number height ); - Create an image with title 'title', data type 'data_type', and size '(width,height)' Image CM_CreateImageForAcquire( Object camera, Object acq_params, String name ); Image CM_AcquireImage( Object camera, Object acq_params ); - Acquire and return an image from 'camera' using parameter set 'acq_params'. void CM_AcquireImage( Object camera, Object acq_params, Image img ); - Acquire an image from 'camera' using parameter set 'acq_params', and place the result in 'img'. Fail if 'img' is not the appropriate size. void CM_AcquireDarkReference( Object camera, Object acq_params, Image img, Object frame_set_info ); - Acquire a dark reference appropriate for images acquired from 'camera' using parameters 'acq_params'. Fail if 'img' is not an appropriate size. Pass 'NULL' into 'frame_set_info'. Fast acquisition The following routines provide a way to get faster readout when doing continuous acquisitions on some cameras. To Object CM_CreateAcquisition( Object camera, Object acq_params ) - Create an 'Acquisition' object from the specified camera and parameters. void ACQ_StartAcquire( Object acquisition ); void ACQ_StopAcquire( Object acquisition ); - Start and stops an acquisition. Between these two calls, an acquisition that specifies continuous readout will cause the CCD to repeatedly acquire frames from the CCD if such behavior is allowed by the controller. void ACQ_ChangeAcquire( Object acquisition Object acq_params ); - Change the acquisition parameters used to acquire images using this acquisition object. The controller will do whatever is necessary for the next 'DoAcquire_LL' to return an image acquired using the new settings. void DoAcquire_LL( Object acquisition , Object acquisition_listener, Image img, Object frame_info ); - Return the next image available from the camera. It is currently up to a particular camera which image in an image sequence this actually returns, up to the following constraints - The images returned by two calls to 'DoAcquire_LL' will return two distinct frames, with the later call returning a strictly later frame in the sequence. Thus, there is currently no guarantee that the frame returned by 'DoAcquire_LL' completed after the call was entered. An camera could, in fact, return every frame of a continuous sequence, returning the oldest frame that has not yet been returned even if later frames are available. Viewer Object CM_StartCameraViewer( Object camera, Object acq_params, Number do_save_changed_parameters, Number prepare_camera ) - Start a viewer that acquires images from 'camera' based on the parameters 'acq_params'. If 'do_save_change_parameters' is 'true' and the acquisition parameters are linked to a tag path, save any changes made on the acquisition parameters via the viewer to the tags. If 'prepare_camera' is true, do standard checks that the camera is in a good state for acquisition ( mainly check if the camera is inserted and prompt to insert it if not ). Object CM_StopCurrentCameraViewer( Number close_view ) - Stop the currently active viewer. Pass 'close_view' as 'true' to close the view when the viewer stops. Object CM_GetCurrentCameraViewer() - Get the currently active viewer. Object CM_RestartCameraViewerFromImage( Image img, Number open_new_window ) - If 'img' was acquired from a camera ( and thus if it has tags specifying the camera and acquisition parameters used ), determine the camera and acquisition parameters used to acquire the image, and start a viewer with those parameters. If 'open_new_window' is 'false', the viewer will place data into 'img', else it will create a new image in which to acquire data and open a window for it. Deprecated but supported functions - 'CM_{Get|Set}Settling' and 'CM_{Get|Set}ShutterIndex' have been deprecated in favor of 'CM_{Get|Set}PrimaryShutterPreExposureCompensation_s' and 'CM_{Get|Set}PrimaryFrameShutterIndex'. If only one shutter is used, the functions are simply equivalent to the new functions as follows CM_{Set|Get}ShutterIndex <==> CM_{Set|Get}PrimaryFrameShutterIndex CM_{Set|Get}Settling <==> CM_{Set|Get}PrimaryShutterPreShutterCompensation The problem with the functions was what should they do if they are acting on a parameter set that has dual shuttering specified. The functions 'CM_{Set|Get}PrimaryFrameShutterIndex' functions specify the primary shutter, which is the one used for dark references and the one whose delays are specified by the primary shutter compensation ( so it is typically the one nearer the CCD ). However, existing script usage in low-dose, which is where dual shuttering is typically used, assumed 'CM_SetShutterIndex' specifies the pre-specimen shutter to ensure it is closed during the readout, and 'CM_SetSettling' specifies the shutter pre exposure compensation for the pre-specimen shutter. Because the pre-specimen shutter is typically the secondary shutter in dual shuttering, we assume that in dual shuttering these functions are specifying which shutter is the secondary shutter and the secondary shutter pre-exposure compensation. Number CM_GetSettling( Object acq_params ); void CM_SetSettling( Object acq_params, Number settling ); - Get/Set the delay in seconds between the time the settling shutter is opened before exposure, and the time the CCD stops clearing. Number CM_GetShutterIndex( Object acq_params ); void CM_SetShutterIndex( Object acq_params, Number index ); - Specify which shutter to use during readout. ( For "MSC" and "FirstLight", 0 is the standard and 1 is the alternate shutter ). Signatures ScriptObject CM_GetCurrentCamera(); ScriptObject CM_CreateAcquisitionParameters( ScriptObject camera, ulong processing, double exposure, ulong bin_x, ulong bin_y ,ulong ccd_t ,ulong ccd_l ,ulong ccd_b ,ulong ccd_r ); ScriptObject CM_CreateAcquisitionParameters_FullCCD( ScriptObject camera, ulong processing, double exposure, ulong bin_x, ulong bin_y ); bool CM_Validate_AcquisitionParameters( ScriptObject camera, ScriptObject acq_params ); bool CM_IsValid_AcquisitionParameters( ScriptObject camera, ScriptObject acq_params ); void CM_CameraCalcImageForm( ScriptObject camera, ScriptObject acq_params, ulong *data_type, ulong *width, ulong *height ); BasicImage CM_CreateImageForAcquire( ScriptObject camera, ScriptObject acq_params, dm_string name ); void CM_AcquireImage( ScriptObject camera, ScriptObject acq_params, BasicImage img ); BasicImage CM_AcquireImage( ScriptObject camera, ScriptObject acq_params );