Summary of API Functions


The following figure lists the API commands and shows the relationships between functional groups of commands.

Two tables below list the API functions by functional group and alphabetically. Designers should consult the referenced topics for detailed descriptions of the API functions. 


Grouped By Function


Detected Cameras


PxLGetNumberCameras()
Get the number of FireWire, USB or IP cameras currently connected to the bus. Will only detect IP cameras that have a valid IP address.
PxLGetNumberCamerasEx()
Get the number of cameras connected to the computer, including IP cameras that do not have a IP address.


Initialize a Camera


PxLInitialize()
Initialize a camera and return the camera handle
PxLInitializeEx()
Initialize a camera in its entirety and obtain the camera handle for subsequent API function calls.


Camera Identification


PxLGetCameraInfo()
Get information about the specified camera
PxLGetCameraInfoEx()
Returns version information about the Pixelink hardware and firmware.  
PxLSetCameraIPAddress()
Set the IP Address of a specified IP camera
PxLSetCameraName()
Set a name for the specified camera


Camera Features

Enumerate Features


PxLGetCameraFeatures()
Get the list of the features supported by the specified camera


Get/Set Features on Camera


PxLGetFeature()
Get the current value of the specified feature
PxLSetFeature()
Set the value of the specified feature


Grouped Alphabetically


API Function Name
Description
PxLAssignController()
Initialize a specific controller, and assign it to a specific camera.
PxLCreateDescriptor()
Create a descriptor for the specified camera
PxLFormatClip()
Convert a Pixelink data stream (.pds) file to a video file (.avi)
PxLFormatClipEx()
Convert either an uncompressed PixeLINK data stream (.pds) file, or a H264 compressed data stream, into a video file (.avi)
PxLFormatImage()
Convert a raw frame residing in an image buffer to an image file (.bmp, .tif, .psd, .jpg)
PxLGetCameraFeatures()
Get the list of the features supported by the specified camera.
PxLGetCameraInfo()
Get information about the specified camera
PxLGetCameraInfoEx()
Returns version information about the Pixelink hardware and firmware.  
PxLGetClip()
Get a video clip and save it as a Pixelink Data stream (.pds) intermediate file
PxLGetCurrentTimeStamp()
Returns the current value of the camera’s ‘clock’ that it uses to timestamp images.
PxLGetEncodedClip()
Saves an encoded (compressed) video clip to a file.
PxLGetErrorReport()
Returns details about the last error that occurred.
PxLGetFeature()
Get the current value of the specified feature.
PxLGetNextFrame()
Get the next image frame from the camera and put it in a image buffer.
PxLGetNumberCameras()
Get the number of cameras currently connected to the bus.
PxLInitialize()
Initialize a camera and return the camera handle
PxLInitializeEx()
Initialize a camera in its entirety and obtain the camera handle for subsequent API function calls.
PxLLoadSettings()
Load settings from non-volatile memory on the camera.
PxLRemoveDescriptor()
Remove the descriptor from the specified camera.
PxLResetPreviewWindow()
Reset the size of the preview window to the size of the streaming video (thereby optimising display performance)
PxLSaveSettings()
Save the current settings to non-volatile memory on the camera.
PxLSetCallback()
Specify a callback function to modify the video data in the preview window or as it is translated into an end-user format.
PxLSetCameraName()
Set a name for the specified camera.
PxLSetFeature()
Set the value of the specified feature
PxLSetPreviewSettings()
Set the preview window settings for the specified camera.
PxLSetPreviewState()
Set the current state of the preview window to be played, stopped or paused.
PxLSetPreviewStateEx()
Similar to PxLSetPreviewState, but accommodates a callback function, called when certain windows based operations are performed to the preview window.
PxLSetStreamState()
Set the current state of the video stream to stopped, started or paused.
PxLUnassignController()
Releases a particular controller, allowing it to be assigned to another camera.
PxLUnintialize()
Uninitialize the specified camera.
PxLUpdateDescriptor()
Set the update mode for the specified descriptor



Summary of API Features


The following figure lists the API Features supported by our cameras.

Designers should consult the referenced topics for detailed descriptions of the API Features. 


Grouped Alphabetically


API Feature Name
Description
FEATURE_ACTUAL_FRAME_RATE
This read-only feature allows the user to query the camera to see what frame rate the camera will use while streaming image data.
FEATURE_BANDWIDTH_LIMIT
When enabled, this feature will place an upper bound on the amount of aggregate bandwidth the camera may use for image data.
FEATURE_BRIGHTNESS
Brightness controls the black level in the image by applying an offset voltage to the pixels before the analog to digital conversion.
FEATURE_EXTENDED_SHUTTER
Extended shutter allows for a multiple slope integration to extend the dynamic range of the camera.
FEATURE_FRAME_RATE
The frame interval and the required bandwidth on the communication bus are fixed by the Frame Rate value. The available frame rate range depends on the bus technology, the current video format, shutter speed, ROI and/or the video mode.
FEATURE_FLIP
Flip controls the orientation of the image. The image can either be flipped horizontally or flipped vertically.
FEATURE_FOCUS
Controls the amount of focus being applied to the Varioptic liquid lens on the camera. You can perform a "One time Auto Focus" or set the focus manually within the range of the specific lens. You may edit the upper and lower limits of this range to help speed up your focus.
FEATURE_GAIN
The gain controls the amplification of the image for the camera.
FEATURE_GAMMA
Gamma controls the contrast in the image and is typically used in microscopy to improve the perceived dynamic range.
FEATURE_GPIO
General Purpose Output (GPO) signals are controlled by this feature. A total of 4 GPO signals can be controlled on all PL-B board level cameras and 2 GPO signals can be controlled on all USB3 cameras.
FEATURE_LOOKUP_TABLE
The Lookup Table (LUT) typically has a number of 2-byte entries that range in value from 0 to 1023 (10-bit depth) or 0 to 4095 (12-bit depth). The LUT is used to implement the Gamma Feature but it can also be used to implement any LUT transfer function required.
FEATURE_MAX_PIXEL_SIZE
This feature allows an application to determine the maximum number of bits the camera can use to represent a pre-formatted (or raw) pixel value.
FEATURE_MAX_PACKET_SIZE
This feature allows an application to control the maximum packet size that the software can receive.
FEATURE_MEMORY_CHANNEL
The memory channel feature stores all camera parameters into non-volatile memory. It is similar to camera configuration files used in frame grabbers and software packages such as Labview. But here the file resides with the camera, not the host PC.
FEATURE_PIXEL_ADDRESSING
The pixel addressing feature reduces the number of pixels that are read from the ROI. Pixel Addressing is controlled by two parameters - a Pixel Addressing mode and a value.
The pixel addressing mode determines how the number of pixels is reduced. The mode of Pixel addressing can be decimate (0), averaging (1), binning (2) or resampling (3).

FEATURE_PIXEL_FORMAT
The Pixel Format refers to the output formatted pixel. In cases where the camera's raw pixel size is larger than the output, the data is truncated and the least significant bits are lost. In cases where the camera's raw pixel size is smaller than the output, the least significant bits in the output data are padded with zeros.
FEATURE_ROI
Region of Interest (ROI) is a feature of most CMOS sensors that allows only a portion of the active sensor to be selected and read out. The benefit of this is a reduction in the total number of pixels and an increase in the readout speed. Often referred to as windowing, the ROI is defined by a top and left pixel as well as a width and height.
FEATURE_ROTATE
Rotate controls the rotation of the image. The image can either be rotated by 90, 180 or 270 degrees in the clockwise direction.
FEATURE_SATURATION
Saturation controls the intensity of the hues in the image. The saturation control allows the hue to be changed from full mono to more than twice the normal. If saturation is set to 100, it has no effect. With saturation set to zero, the colour camera behaves as a monochrome camera.
FEATURE_SHARPNESS
The sharpness feature is a standard convolution filter applied to the intensity (luma) channel as where is the Laplacian of the pixel luma at location (i,j). The Laplacian is implemented as a 3x3 convolution kernel filter as follows.
In the equation, Ko is scaling factor applied to the original pixel value which, in the sharpness filter, is set to one. Ks is a scaling factor applied to the result of the Laplacian.  

FEATURE_SHARPNESS_SCORE
A set of control information the camera uses to calculate the SharpnessScore of an image. The SharpnessScore of the image, is returned in the SharpnessScore field of the FRAME_DESC structure that is returned with each image capture.
FEATURE_SHUTTER
The shutter feature controls the exposure time of the sensor. Increasing the shutter integration time makes the image brighter. On CMOS sensors, increasing the shutter integration time will also increase the amount of noise in the image.
FEATURE_SPECIAL_CAMERA_MODE
This feature can be used to put the camera in to (and out of) a 'special' mode of operation.
FEATURE_BODY_TEMPERATURE
FEATURE_SENSOR_TEMPERATURE

The Temperature feature is a read only feature that provides an indication of the temperature of the sensor chip. This is important because sensor performance is related to the temperature of the sensor. Typically, read noise can double for every 10 degree increase in temperature. In warm environments, the temperature sensor can be used to assess the effectiveness of the mounting hardware at removing heat form the camera.
FEATURE_TRIGGER_WITH_CONTROLLED_LIGHTING
Trigger with Controlled Lighting allows control over the manner in which rolling shutter or fast-reset shutter cameras function when using a trigger. In normal operation, a rolling shutter camera is resetting, exposing and reading out information concurrently. This results in consistent exposure times and faster frame rates. However, since the rolling shutter is only exposing a portion of the sensor at a time, this mode is not effective at stop motion imaging.
To capture stop motion with a rolling shutter camera requires controlled lighting using a strobe, shutter or both. The sensor must be fully reset prior to the exposure beginning. Then, once the exposure is complete, the sensor starts readout. During the readout, the sensor remains sensitive to incident illumination - hence the need for controlled lighting.

FEATURE_TRIGGER
Trigger controls the response of the camera to an external trigger input. Trigger functionality is required for industrial and machine vision applications where the timing of the image capture is determined by external events. The trigger can operate in a number of modes which provide flexibility when interfacing the camera with external equipment.
FEATURE_WHITE_BAL
White balance defines the colour temperature of the light source. Calibrations are performed for 3200 K (incandescent), 5000 K (daylight 1) and 6500 K (daylight 2). The camera uses this information to select from one of a number of possible colour correction matrices. Turning the White Balance off disables the colour correction.  
FEATURE_WHITE_SHADING
The White shading feature provides control over the individual red, green and blue channel gains so that non-standard colour balance can be achieved. One-push Auto will attempt to white balance the gains (match the histogram peaks of the brightest area in each colour channel) based on the image data in the current ROI.

 

.