Basics and Terminology

Basic terms, types and principles used across the PVCAM and PVCAM SDK documentation.

Defined Data Types

In order to work effectively across platforms, the number of bytes in a variable must be consistent. Therefore, new types have been defined for PVCAM API. These types are defined in master.h and pvcam.h header files.

Type	Explanation
rs_bool	TRUE (1) or FALSE (0) value
int8	signed 8-bit integral value
uns8	unsigned 8-bit integral value
int16	signed 16-bit integral value
uns16	unsigned 16-bit integral value
int32	signed 32-bit integral value
uns32	unsigned 32-bit integral value
ulong64	unsigned 64-bit integral value
long64	signed 64-bit integral value
enum	treated as signed 32-bit integral value
flt32	32-bit floating point value
flt64	64-bit floating point value
smart_stream_type	structure for S.M.A.R.T. streaming
rgn_type	structure holding additional region information
FRAME_INFO	structure holding additional frame information

For historical reasons and also for backward compatibility, the PVCAM public headers contain definitions of pointer type and constant pointer type for each basic data type as listed in Table 1. Usually, these types have _ptr or _const_ptr suffix. However, it is not recommended to use these types in any new code.

Function Arguments Passing

When arguments are passed in or out of functions, a careful approach has to be taken to determine which arguments the user should set and which arguments are set by the function. In PVCAM, virtually all the information is exchanged through arguments since the function return value is reserved for indicating errors.

The following rules can be used to avoid the confusion:

• Non-pointers always send information to a function.
• Constant pointers always send information to a function. The data is not altered.
• Non-constant pointers generally return information from a function.

In a few cases, the non-constant pointer is also used as input function argument. For instance, the camera name string in pl_cam_open function is passed as non-const pointer and cannot be changed without breaking binary compatibility. Another example is void pointer to raw frame data.

Note

Please, refer to the section Working With Parameters under code samples to obtain more detailed information about how to work with PVCAM parameters.

Image Buffer

Whether exposures include multiple images or complex sequences, the images are stored in a buffer.

• Single Exposure: All the data is stored in a single buffer.
  • Full Sensor: A single exposure where the entire sensor is treated as one region and image data are collected over the full sensor. Full sensor is actually a special case of custom region.
    
  • Custom Region: A single exposure with a region. Less data than what the full sensor would produce is stored in the single buffer.
    
• Multiple Exposures - Sequences: The data is stored in several image arrays that are stored inside a single buffer.
  • Full Sensor: A series of exposures with single region which is equal to full sensor size.
    
  • Custom Region: A series of exposures with a single region.
    

PVCAM collects data very efficiently, but moving the data in and out of a buffer involves extra processing time. If speed is crucial, the following options may minimize the processing time:

• Don't use an extra buffer. The data is collected in a user-specified memory location at maximum efficiency (see pl_exp_start_seq). As discussed in Data Array, this array can be accessed directly.

Coordinates Model

In some cameras, the sensor orientation is fixed. This fixed position places the origin in a predetermined location and gives each pixel an [x,y] location.

In Teledyne Photometrics cameras, the sensor orientation may not only differ from camera to camera, but the orientation may also change when the application changes. Therefore, a serial, parallel (s,p) coordinates system is used. This terminology is historically based on the CCD sensor technology. In this system, the origin is located in the corner closest to the serial register readout, and the coordinates increase as the locations move away from the origin. The diagram below illustrates how the coordinates are unaffected by the sensor orientation.

The naming convention is the same for sCMOS-type sensors, however, the serial size usually represents the sensor imaging area width (number of columns) and the parallel size defines the sensor imaging area height (number of rows).

Regions and Images

A region is a user-defined, rectangular exposure area on the sensor. As shown in the diagram above, the user defines the region by selecting s1,p1 and s2,p2, the diagonal corners of the region. An image is the data collected from a region. Camera reads out the image from the sensor, delivers it to the host and PVCAM then stores it in a buffer.

Binning Factors

For data collection, two other parameters are needed: the serial and parallel binning factors. A binning of 1 in both directions reads out each pixel at full lateral resolution. A binning of 2 in both directions combines data from four pixels, cutting the lateral resolution in half. The number of pixels read out is determined as (s2-s1+1)/sbin in the serial direction, and (p2-p1+1)/pbin in the parallel direction. If these equations do not produce an integer result, the remaining pixels are ignored.

Including binning, a data collection region can be fully specified with six parameters: s1,p1,s2,p2,sbin,pbin. Since these values are zero-indexed, the following is true:

smax = serial_size - 1
pmax = parallel_size - 1

Data Array

When pixels are read out, they are placed in the data array indicated by the pointer passed into pl_exp_start_cont or pl_exp_start_seq. The pixels are placed into the buffer in the order they are read from the sensor:

Display Orientation

The pixel at [0,0] coordinates is displayed in the upper left corner and subsequent pixels are painted from left to right, line by line. Although display coordinate configuration can be performed in the display routine, factors such as optical path, camera rotation, and readout port selection may cause the image to appear in a different position or orientation (for example an EMCCD camera may produce mirrored image if the EM port is selected).