EXCELITAS TECHNOLOGIES pco.convert Microscope Camera User Manual
- July 30, 2024
- EXCELITAS TECHNOLOGIES
Table of Contents
EXCELITAS TECHNOLOGIES pco.convert Microscope Camera
Specifications
- Product Name: pco. convert
- Version: 1.52.0
- License: Creative Commons Attribution-NoDerivatives 4.0International License
- Manufacturer: Excelitas PCO GmbH
- Address: Donaupark 11, 93309 Kelheim, Germany
- Contact: +49 (0) 9441 2005 50
- Email: pco@excelitas.com
- Website: www.excelitas.com/product-category/pco
Product Usage Instructions
General Information
The pco.convert offers various functions for color and pseudo color
conversion. It is important to follow the instructions provided in the user
manual for optimal performance.
Convert API Function Description
The Convert API provides a set of functions for manipulating color and
image data. Below are some key functions:
-
* **PCO_ConvertCreate:** Create a new conversion instance.- PCO_ConvertDelete: Delete a conversion instance.
- PCO_ConvertGet: Get conversion settings.
Color and Pseudo Color Conversion
The pco.convert supports both black and white conversion as well as color
conversion. Follow the specific instructions provided in the manual for each
type of conversion.
FAQ
-
Q: How do I perform a color conversion using pco.convert?
- A: To perform a color conversion, use the PCO_ConvertGet function with the appropriate parameters as outlined in the user manual.
-
Q: Can I delete a conversion instance?
- A: Yes, you can delete a conversion instance using the PCO_ConvertDelete function.
user manual
pco.convert
Excelitas PCO GmbH asks you to carefully read and follow the instructions in this document. For any questions or comments, please feel free to contact us at any time.
- telephone : + 49 (0) 9441 2005 50
- fax: + 49 (0) 9441 2005 20
- postal address: Excelitas PCO GmbH Donaupark 11 93309 Kelheim, Germany
- email: pco@excelitas.com
- web : www.excelitas.com/product-category/pco
pco.convert
user manual 1.52.0
Released May 2024
©Copyright Excelitas PCO GmbH
This work is licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nd/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
General
-
This convert SDK description can be used to implement the PCO convert routines in proprietary applications, which are used to control PCO cameras. It is prohibited to use the convert routines with third party cameras.
-
The pco.convert sdk consists of two parts: The LUT conversion functions pco.conv.dll and the dialog functions pco_cdlg.dll .
The conversion functions are used to convert data areas, b/w and color, with a resolution of more than 8 bit per pixel to either b/w data areas with a resolution of 8 bit per pixel or color data areas with a resolution of 24 (32) bit per pixel. The DLL also includes functions to create and fill the various convert objects. -
The second part of the API contains the dialog functions. The dialogs are simple GUI dialogs which enable the user to set the parameters of the convert objects. The dialog functions are included in the pco_cdlg.dll and are based on some functions of the pco.conv.dll.
-
In the pco.sdk for pco cameras there exist two samples, which make use of the convert sdk. One is the Test_cvDlg sample and the other is the sc2_demo. Please take a look at those samples in order to ’see’ the convert sdk functions in action.
B/W And Pseudo Color Conversion
The conversion algorithm used in the b/w function is based on the following
simple routine
where
- pos is the counter variable
- dataout is the output data area
- datain is the input data area
- lutbw is a data area of size 2n containing the LUT, where n = resolution of the input area in bits per pixel
In the pseudocolor function the basic routine to convert to a RGB data area is:
where
- pos is the input counter variable
- pout is the output counter variable
- dataout is the output data area
- datain is the input data area
- lutbw is a data area of size 2n containing the LUT, where n = resolution of the input area in bits per pixel
- lutred, lutgreen, lutblue are data areas of size 2n containing the LUT, where n = resolution of the output area in bit per pixel.
Color Conversion
- CCD color sensors used in PCO color cameras have filters for the colors red, green, and blue. Each pixel has one type of filter, thus originally you do not get full color information for each pixel. Rather each pixel delivers a value with a dynamic range of 12 bits for the color which passes the filter.
- All color cameras at PCO work with the Bayer-filter DE mosaicking. The color filter pattern of those color image sensors can be reduced to a 2×2 matrix. The image sensor itself can be seen as a matrix of those 2×2 matrixes.
- Suppose this color pattern
The color itself is only an interpretation of the matrix. This interpretation will be done by a so called demosaicking algorithm. The pco_conv.dll works with a special proprietary method.
Convert API Function Description
PCO_ConvertCreate
Description
Creates a new convert object based on the PCO_SensorInfo structure. The
created convert handle will be used during the conversion. Please call
PCO_ConvertDelete before the application exits and unloads the convert dll.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE* | Pointer to a handle which will receive the created convert object |
| strSensor | PCO_SensorInfo* | Pointer to a sensor information structure. Please |
do not forget to set the wSize parameter.
iConvertType| int| Variable to determine the conversion type, either b/w,
color, pseudo color or color 16
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_ConvertDelete
Description
Deletes a previously created convert object. It is mandatory to call this
function before closing the application.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Error code otherwise. |
PCO_ConvertGet
Description
Gets all the values of a previously created convert object.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pstrConvert | PCO_Convert* | Pointer to a pco convert structure |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Error code otherwise. |
PCO_ConvertSet
Description
Sets necessary values for a previously created convert object.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pstrConvert | PCO_Convert* | Pointer to a pco convert structure |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_ConvertGetDisplay
Description
Gets the PCO_Display structure
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pstrDisplay | PCO_Display* | Pointer to a pco display structure |
Return value
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pstrDisplay | PCO_Display* | Pointer to a pco display structure |
PCO_ConvertSetDisplay
Description
Sets the PCO_Display structure
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pstrDisplay | PCO_Display* | Pointer to a pco display structure |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_ConvertSetBayer
Description
Sets the Bayer structure values of a previously created convert object. Use
this functions to change the Bayer pattern parameters.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pstrBayer | PCO_Bayer* | Pointer to a PCO Bayer structure |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_ConvertSetFilter
Description
Sets the filter structure values of a previously created convert object.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| prefilter | PCO_Filter* | Pointer to a pco filter structure |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_ConvertSetSensorInfo
Description
Sets the PCO_SensorInfo structure for a previously created convert object
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pstrSensorInfo | PCO_SensorInfo* | Pointer to a sensor information structure. |
Please do not forget to set the wSize parameter
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_SetPseudoLut
Description
Load the three pseudolut color tables of plot
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| pseudo_lut | unsigned char* | Pointer to pseudo lut color values (R,G,B colors: |
256 * 3 bytes, or 4 bytes)
inumcolors| int| Set to either 3 for R,G,B or 4 for R,G,B,A
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_LoadPseudoLut
Description
Loads a pseudo color lookup table to the convert object. This function can
be used to load some of the predefined or self created pseudo lookup tables.
Prototype
Parameter
Name Type Description
ph| HANDLE| Handle to a previously created convert object
format| int| 0| lt1, 1| lt2, 2| lt3, 3| lt4
filename| char*| Name of the file to load
Return value
Name Type Description
ph| HANDLE| Handle to a previously created convert object
format| int| 0| lt1, 1| lt2, 2| lt3, 3| lt4
filename| char*| Name of the file to load
PCO_Convert16TO8
Description
Convert picture data in b16 to 8bit data in b8 (grayscale)
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| mode | int | Mode parameter |
| icolmode | int | Color mode parameter |
| width | int | Width of the image to convert |
| height | int | Height of the image to convert |
| b16 | word* | Pointer to the raw image |
| b8 | byte* | Pointer to converted 8bit b/w image |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_Convert16TO24
Description
Convert picture data in b16 to 24bit data in b24 (grayscale)
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| mode | int | Mode parameter |
| Name | Type | Description |
| --- | --- | --- |
| icolmode | int | Color mode parameter |
| width | int | Width of the image to convert |
| height | int | Height of the image to convert |
| b16 | word* | Pointer to the raw image |
| b24 | byte* | Pointer to converted 24bit color image |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_Convert16TOCOL
Description
Convert picture data in b16 to RGB data in b8 (color)
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| mode | int | Mode parameter |
| icolmode | int | Color mode parameter |
| width | int | Width of the image to convert |
| height | int | Height of the image to convert |
| b16 | word* | Pointer to the raw image |
| b8 | byte* | Pointer to converted 24bit color image |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_Convert16TOPSEUDO
Description
Convert picture data in b16 to pseudo color data in b8 (color)
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| mode | int | Mode parameter |
| icolmode | int | Color mode parameter |
| width | int | Width of the image to convert |
| height | int | Height of the image to convert |
| b16 | word* | Pointer to the raw image |
| b8 | byte* | Pointer to converted 24bit pseudo color image |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_Convert16TOCOL16
Description
Convert picture data in b16 to RGB data in b16 (color)
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| mode | int | Mode parameter |
| Name | Type | Description |
| --- | --- | --- |
| icolmode | int | Color mode parameter |
| width | int | Width of the image to convert |
| height | int | Height of the image to convert |
| b16in | word* | Pointer to the raw image |
| b16out | word* | Pointer to converted 48bit color image |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_GetWhiteBalance
Description
Gets white balanced values for color_tempand tint
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| ph | HANDLE | Handle to a previously created convert object |
| color_temp | int* | int pointer to get the calculated color temperature |
| tint | int* | int pointer to get the calculated tint value |
| mode | int | Mode parameter |
| width | int | Width of the image to convert |
| height | int | Height of the image to convert |
| gb12 | WORD* | Pointer to raw picture data array |
| x_min | int | Rectangle to set the image region to be used for calculation |
| y_min | int | Rectangle to set the image region to be used for calculation |
| x_max | int | Rectangle to set the image region to be used for calculation |
| y_max | int | Rectangle to set the image region to be used for calculation |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_GetMaxLimit
Description
GetMaxLimit gets the RGB values for a given temp and tint. The max value
within the convert control dialog must not exceed the biggest value of the RGB
values, e.g. in case R is the biggest value, the max value can increase till
the R value hits the bit resolution (4095). Same condition must be met for
decreasing the max value, e.g. in case B is the lowest value, the max value
can decrease till the B value hits the min value.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| r_max | float* | Pointer to a float receiving the max red value |
| g_max | float* | Pointer to a float receiving the max green value |
| b_max | float* | Pointer to a float receiving the max blue value |
| temp | float | Color temperature |
| tint | float | Tint setting |
| output_bits | int | Bit resolution of the converted image (usually 8) |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_GetColorValues
Description
Gets color temperature and tint for given R,G,B max values.
GetColorValuesis used only in pco.camware . It
calculates the color temperature and tint based on the Rmax,Gmax,Bmax values
of the old color lut. The calculated values are used to convert old b16 and
tif16 images with the new convert routines.
Prototype
Parameter
| Name | Type | Description |
|---|---|---|
| pfColorTemp | float* | Pointer to a float for receiving the color temperature |
| pfColorTemp | float* | Pointer to a float for receiving the color tint |
| iRedMax | int | Integer to set the current max value for red |
| iGreenMax | int | Integer to set the current max value for green. |
| iBlueMax | int | Integer to set the current max value for blue |
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_WhiteBalanceToDisplayStruct
Description
Calculates the white balance and sets the values to the strDisplaystruct
while maintaining the limits. Gets the struct str Display from the convert
Handle internally
Prototype
Parameter
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
PCO_GetVersionInfoPCO_CONV
Description
Returns version information about the dll.
Prototype
Parameter
Return value
| Name | Type | Description |
|---|---|---|
| ErrorMessage | int | 0 in case of success, Errorcode otherwise. |
Typical Implementation
This typical step by step implementation shows the basic handling
- Declarations
- Set all buffer ’size’ parameters to the expected values:
- Set the sensor info parameters and create the convert object
- Optionally open a convert dialog
- Set the min and max value to the desired range and set them to the convert object
- Do the convert and set the data to the dialog if dialog is open
- Close the optionally opened convert dialog
- Close the convert object:
See the Test_cvDlg sample in the pco.sdk sample folder. Starting with v1.20, the range of the negative tint value has been doubled.
- postal address: Excelitas PCO GmbH Donaupark 11 93309 Kelheim, Germany
- telephone: +49 (0) 9441 2005 0
- e-mail: pco@excelitas.com
- web : www.excelitas.com/pco
References
- Deed - Attribution-NoDerivatives 4.0 International - Creative Commons
- PCO | Excelitas
- PCO | Excelitas
Read User Manual Online (PDF format)
Read User Manual Online (PDF format) >>