PVCAM 2.7 User Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 168
| Download | |
| Open PDF In Browser | View PDF |
4411-0094
Version 2.7.0
December 28, 2004
4411-0094
© Copyright 2003-2004 Princeton Instruments
a division of Roper Scientific, Inc.
3660 Quakerbridge Rd.
Trenton, NJ 08619
TEL: 800-874-9789 / 609-587-9797
FAX: 609-587-1970
All rights reserved. No part of this publication may be reproduced by any means without the written
permission of Princeton Instruments, a division of Roper Scientific, Inc. ("Princeton Instruments").
Printed in the United States of America.
Macintosh is a registered trademark of Apple Computer, Inc.
Roper Scientific and PVCAM are registered trademarks of Roper Scientific, Inc.
UNIX was a registered trademark of UNIX System Laboratories, Inc. and now is registered to the X/Open
Consortium.
Windows is a registered trademark of Microsoft Corporation.
The information in this publication is believed to be accurate as of the publication release date. However,
Roper Scientific, Inc. does not assume any responsibility for any consequences including any damages
resulting from the use thereof. The information contained herein is subject to change without notice.
Revision of this publication may be issued to incorporate such change.
Table of Contents
Chapter 1: SDK
1
What is the SDK? ............................................................................................................................ 1
Contact Information ......................................................................................................................... 1
Chapter 2: PVCAM, A High-Level C Library
3
Introduction...................................................................................................................................... 3
System Overview ............................................................................................................................. 3
Hardware Support ............................................................................................................................ 3
Library Classes ................................................................................................................................ 4
Documentation Style........................................................................................................................ 4
Defined Types.................................................................................................................................. 5
Naming Conventions ....................................................................................................................... 6
Include Files..................................................................................................................................... 6
Parameter Passing and const............................................................................................................ 7
CCD Coordinates Model.................................................................................................................. 7
Regions and Images................................................................................................................... 7
Binning Factors ......................................................................................................................... 8
Data Array ................................................................................................................................. 8
Display Orientation ................................................................................................................... 8
Port and Speed Choices ................................................................................................................... 8
Frame Transfer............................................................................................................................... 10
Interline.......................................................................................................................................... 10
Kinetics .......................................................................................................................................... 10
Custom Chip .................................................................................................................................. 11
Custom Timing .............................................................................................................................. 11
Image Smear .................................................................................................................................. 11
Sequences....................................................................................................................................... 12
Sequence Parameters IDs/Constants.............................................................................................. 13
Circular Buffer ............................................................................................................................... 13
Clear Modes ................................................................................................................................... 15
Exposure Modes ............................................................................................................................ 16
Exposure: TIMED_MODE ..................................................................................................... 16
Exposure: VARIABLE_TIMED_MODE ............................................................................... 16
Exposure: TRIGGER_FIRST_MODE.................................................................................... 17
Exposure: STROBED_MODE................................................................................................ 17
Exposure: BULB_MODE ....................................................................................................... 18
Exposure: FLASH_MODE ..................................................................................................... 18
Open Delay, Close Delay............................................................................................................... 19
Shutter Control............................................................................................................................... 20
iii
iv
PVCAM Manual
Version 2.7
Exposure Loops ............................................................................................................................. 20
Image Buffers ................................................................................................................................ 24
Source Code Examples .................................................................................................................. 25
Chapter 3: Camera Communications (Class 0)
27
Introduction.................................................................................................................................... 27
List of Available Class 0 Functions ............................................................................................... 27
List of Available Class 0 Parameter IDs........................................................................................ 27
Class 0 Functions ........................................................................................................................... 28
Class 0 Parameter IDs.................................................................................................................... 38
Chapter 4: Error Reporting (Class 1)
41
Introduction.................................................................................................................................... 41
Error Codes .................................................................................................................................... 42
List of Available Class 1 Functions ............................................................................................... 42
Class 1 Functions ........................................................................................................................... 43
Chapter 5: Configuration / Setup (Class 2)
45
Introduction.................................................................................................................................... 45
List of Available Class 2 Functions ............................................................................................... 46
List of Available Class 2 Parameter IDs........................................................................................ 46
Class 2 Functions ........................................................................................................................... 48
Class 2 Parameter IDs.................................................................................................................... 53
Chapter 6: Data Acquisition (Class 3)
67
Introduction.................................................................................................................................... 67
List of Available Class 3 Functions ............................................................................................... 67
List of Available Class 3 Parameter IDs........................................................................................ 67
Defining Exposures........................................................................................................................ 68
New Structures............................................................................................................................... 68
Exposure Mode Constants ............................................................................................................. 69
Class 3 Functions ........................................................................................................................... 70
Class 3 Parameter IDs.................................................................................................................... 90
Chapter 7: Buffer Manipulation (Class 4)
93
Introduction.................................................................................................................................... 93
List of Available Class 4 Functions ............................................................................................... 93
New Constants ............................................................................................................................... 94
Image Handles and Pointers........................................................................................................... 94
Class 4 Functions ........................................................................................................................... 95
Chapter 8: Code Examples
111
Example 1: pl_get_param & pl_get_enum_param ...................................................................... 111
Example 2: pl_set_param............................................................................................................. 115
Example 3: Circular Buffer.......................................................................................................... 117
Table of Contents
v
Latest Frame Mode (FOCUS) ............................................................................................... 117
Oldest Frame Mode (NFRAME)........................................................................................... 119
Example 4: Standard Mode Acquisition ...................................................................................... 121
Appendix A: Error Codes
123
Appendix B: Obsolete Functions
133
Obsolete Class 0 Functions.......................................................................................................... 136
Obsolete Class 2 Functions.......................................................................................................... 143
Obsolete Class 3 Functions.......................................................................................................... 153
Index
157
List of Tables
Table 1. New Number Types .......................................................................................................... 5
Table 2. New Pointer Types............................................................................................................ 6
Table 3. Standard Abbreviations..................................................................................................... 6
Table 4. Two Port Camera Example............................................................................................... 9
Table 5. Error Codes................................................................................................................... 123
Table 6. Obsolete Class 0 Functions and Their pl_set_param/pl_set_param Equivalents.......... 133
Table 7. Obsolete Class 2 Functions and Their pl_set_param/pl_set_param Equivalents.......... 133
Table 8. Obsolete Class 3 Functions and Their pl_set_param/pl_set_param Equivalents.......... 135
vi
PVCAM Manual
This page intentionally left blank.
Version 2.7
Chapter 1:
SDK
What is the SDK?
SDK — Roper Scientific’s Software Development Kit — allows programmers to access and use the
capabilities of PVCAM© — Programmable Virtual Camera Access Method Library. (PVCAM is
described in detail in the chapters that follow.)
Both the SDK and PVCAM are designed to be platform independent, so the functions described in this
manual work with all supported operating systems. Specific information for installing and using the
library with your particular platform (Windows©, Macintosh©, or UNIX©) is contained in the Read Me
file included on the disk that came with your SDK. Please consult this Read Me file for information on:
•
System requirements
•
Linking PVCAM to your software
•
Initializing PVCAM
•
Device drivers
•
Platform specific files
Contact Information
Princeton Instruments' manufacturing facility is located at the following address:
Roper Scientific, Inc.
3660 Quakerbridge Road
Trenton, NJ 08619 (USA)
TEL: 800-874-9789 / 609-587-9797
TEL: 609-587-1970
Customer Support E-mail: techsupport@princetoninstruments.com
For technical support and service outside the United States, see our web page at
www.princetoninstruments.com. An up-to-date list of addresses, telephone numbers, and e-mail addresses
of Princeton Instruments' overseas offices and representatives is maintained on the web page.
1
2
PVCAM Manual
This page intentionally left blank.
Version 2.7
Chapter 2:
PVCAM, A High-Level C Library
Introduction
PVCAM is an ANSI C library of camera control and data acquisition functions. This library, which is
identical across platforms and operating systems, provides an interface that allows developers to specify
the camera's setup, exposure, and data storage attributes.
Note: Many Photometrics cameras support ICL scripting language that provides detailed low-level
control of exposure and CCD readout. None of the Princeton Instruments cameras support ICL scripting.
System Overview
To use PVCAM, a system must include camera hardware and software, a host computer, and the
PVCAM library.
Host Computer
Application
PVCAM
Camera
Option
Option
Diagnostics
Device
Driver
Data
Link
Camera
Interface
Boards
Support
Software
Hardware Support
Roper Scientific produces two lines of hardware: Photometrics brand and Princeton Instruments
brand. Version 2.7 of the PVCAM library supports the following Princeton Instruments hardware:
•
PentaMAX Version 5.0
•
ST-133 Controlled Cameras (PCI and USB 2.0)
•
PIXIS
Note: Macintosh® computers are not currently supported for Princeton Instruments hardware.
3
4
PVCAM Manual
Version 2.7
Library Classes
The basic PVCAM library supports the following five classes of camera and buffer control:
0. Camera Communications
These functions establish communication paths between
the high-level application software and the device driver.
They also establish some low-level functions for
controlling the camera hardware.
1. Error Reporting
These functions monitor and report on other library
functions. When an error occurs, a function can be called
to return a unique error code.
2. Configuration/Setup
These functions initialize the library and set up the
hardware and software environments. They also control
and monitor the camera hardware, and allow the user to
set parameters such as camera gain and temperature.
3. Data Acquisition
These functions define how the image data are collected.
4. Buffer Manipulation
These functions report buffer information and control
buffer allocation and editing.
Note: Other classes are supported in optional plug-ins. Contact the factory for more information
about plug-ins for PVCAM.
Documentation Style
This manual describes the functional aspects of using PVCAM and various controls for Roper
Scientific® cameras (Chapter 2), gives reference pages for all of the function calls (Chapter 3
through Chapter 7), gives code examples (Chapter 8), provides a list of the defined error codes
(Appendix A) and lists the function calls that are obsolete but still supported in the library
(Appendix B).
Chapter 2: PVCAM, A High-Level C Library
Defined 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. These typedefs are given in the header file
master.h.
Type
Explanation
rs_bool*
true (non-0) 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
enum
treat as unsigned 32-bit integral value
flt64
64-bit floating point value
Table 1. New Number Types
*Note: The type ‘rs_bool’ has replaced the deprecated ‘boolean’ type. This is due to a size
difference of the ‘boolean’ type on the Windows platform. Namely, defines a
‘boolean’ type of a different size. Including in the same translation unit as
“master.h” compiles the wrong ‘boolean’ and causes subtle memory access violations. It is
strongly recommended to use the new ‘rs_bool’ type instead to avoid this potential clash.
Since Roper Scientific® camera data and analyses depend on bit depth, the new types give values
that are consistent with the size of the bit depth.
Each new type is composed of the appropriate combinations of int, short, long, or other types that
give the appropriate length for each value. The 8-bit types are the smallest type that holds 8 bits,
16-bit types are the smallest type holding 16 bits, and so forth.
The following list includes the new types defined for use in PVCAM. Additional derived types
always begin with the base name followed by _ptr or _const_ptr.
Type
Pointer
Pointer to Constant Type
rs_bool
rs_bool_ptr
rs_bool_const_ptr
char
char_ptr
char_const_ptr
int8
int8_ptr
int8_const_ptr
uns8
uns8_ptr
uns8_const_ptr
int16
int16_ptr
int16_const_ptr
uns16
uns16_ptr
uns16_const_ptr
int32
int32_ptr
int32_const_ptr
uns32
uns32_ptr
uns32_const_ptr
flt64
flt64_ptr
flt64_const_ptr
5
6
PVCAM Manual
Type
Pointer
Version 2.7
Pointer to Constant Type
rgn_type
rgn_ptr
rgn_const_ptr
export_ctrl_type
export_ctrl_ptr
export_ctrl_const_ptr
Table 2. New Pointer Types
Naming Conventions
To shorten names and improve readability, standard abbreviations are used for common words and
phrases. These abbreviations are used in function and variable names.
adc=analog-to-digital converter
dly=delay
num=number
addr=address
dup=duplicate
ofs=offset
bin=binning
err = error
par=parallel
buf=buffer
exp=exposure
pix=pixel
cam=camera
expt=export
ptr=pointer
cfg=configuration
hbuf=buffer handle
rpt=report
chan=channel
hcam=camera handle
rgn=region
clr=clear
hi=high
ser=serial
cmd=command
hrgn=region handle
shtr=shutter
comm=communication
init=initialize
spd=speed
ctr=counter
len=length
tmp=temp
ctrl=control
lo=low
totl=total
diag=diagnostics
mem=memory
xfr=transfer
Table 3. Standard Abbreviations
In PVCAM, num always means current selection number, while totl or entries is used for
total different possibilities.
A leading h usually signifies a type of handle, such as the camera handle (hcam). A handle is a
16-bit number that refers to an object.
Include Files
Any program using PVCAM must include the following files:
•
master.h
system-specific definitions and types
•
pvcam.h
constants and prototypes for all functions
master.h must be included before pvcam.h.
Chapter 2: PVCAM, A High-Level C Library
7
Parameter Passing and const
When parameters are passed in or out of functions, it may be difficult to determine which
parameters the user should set and which parameters are set by the function. This is particularly
difficult in PVCAM, because virtually all information is exchanged through parameters (the
function return value is reserved for indicating errors).
A few simple rules help resolve the confusion:
•
Pointers generally return information from a function.
•
Non-pointers always send information to a function.
In a few cases, such as structures and arrays, a pointer is passed even though the data are being sent in
to the function. This is done to reduce overhead and to speed function calls, but it conflicts with the
rules above. To solve this problem, when a structure or array (pointer) is sent as input to a function,
the _const_ptr type is used to indicate that the function will not (and can not) change the data.
Note: const_ptr (pointers to const) always sends data into a function. The data is not altered.
CCD Coordinates Model
In many cameras, the CCD orientation is fixed. This fixed position places the origin in a
predetermined location and gives each pixel an x,y location.
In Roper Scientific cameras, the CCD orientation is not only different from camera to camera, but
the orientation may also change when the application changes. Therefore, we use a serial, parallel
(s,p) coordinates system. 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 CCD orientation.
Parallel Direction
(0, 0)
Serial Register
(s1, p1)
Serial Direction
(0, 0)
CCD
Serial Register
Serial Direction
(s2, p2)
Parallel Direction
(s1, p1)
(s2, p2)
CCD
Regions and Images
A region is a user-defined, rectangular exposure area on the CCD. As seen 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. PVCAM reads out the image, then stores it in a buffer.
8
PVCAM Manual
Version 2.7
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 four pixels, cutting the lateral resolution in half, but quadrupling the lightcollecting area. The number of pixels read out are 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 0 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 an array in the
following order:
Serial Register
1 2 3
4 5 6
7 8 9 10 11 12 13 14
Data Array
15 16 17 18
19 20 21 22 23 24
25 26 27 28 29 30
31 32 33 34 35 36
CCD
Display Orientation
Some users have expressed an interest in having the data in video coordinates. With video
coordinates, 0,0 is displayed in the upper left corner, and subsequent pixels are painted from left to
right. Although video coordinate configuration can be done in the display routine, factors such as
the optical path, the camera rotation, and which readout port is selected may cause the image to
appear in a different position.
Port and Speed Choices
The CCD in a camera will have one or more output nodes from which the analog pixel stream will
be read. These nodes are referred to as “Readout Ports”. The signal from a readout port is passed to
an analog signal processing chain and then passed to an analog to digital converter (ADC). The
ADC operates at one or more digitization rates and has a set of parameters associated with it. In
PVCAM, the choice of speed (digitization rate) and associated ADC parameters are organized into
a Speed Table. In some cameras, different readout ports will be connected to different analog
processing chains and different ADCs. The most general method for setting up the port and speed
choices is to make the speed choices dependent upon the port selection.
To view the port settings, call pl_get_param with PARAM_READOUT_PORT with the
ATTR_COUNT attribute to determine how many ports are available in your camera. Next, iterate
through each choice, calling pl_get_enum_param with PARAM_READOUT_PORT and record the
enumerated types returned for each valid port. Next, iterate through each of the enumerated valid
Chapter 2: PVCAM, A High-Level C Library
9
ports calling pl_set_param with PARAM_READOUT_PORT. For each valid port, build a speed table
that will then be associated with that port.
Camera speed is determined by CCD readout speed. Since readout speed is determined by a number
of constraints, getting consistent results depends on using the appropriate camera and hardware
settings. To maintain consistency, each camera has the appropriate readout speeds and associated
hardware controls loaded into the speed table. To build the speed table, for each valid port call
pl_get_param with PARAM_SPDTAB_INDEX with the ATTR_COUNT attribute to determine how
many speed entries are allowed on your camera. Then iterate through each choice to get the
associated information for that entry. The steps you should take in setting up the readout ports and
associated speed tables are as follows:
1. pl_get_param with PARAM_READOUT_PORT with ATTR_COUNT to get the total number
of valid ports.
2. pl_get_enum_param with PARAM_READOUT_PORT to get the enumerated port constants.
3. For each port constant, pl_set_param with PARAM_READOUT_PORT, and build a speed
table for each.
Table 4 is an example of a camera with two readout ports. Port 1 has one speed associated with it
and Port 2 has three speeds. Note that the terms "Port 1" and "Port 2" are generic and are only being
used to illustrate the example.
The user chooses the port and then the speed table entry number, and the camera is configured
accordingly. The user can then choose one of the gain settings available for that speed table entry
number. For example, the user chooses Port 2 and speed index one. This selection provides a 16-bit
camera with a pixel time of 500 nanoseconds (a 2 MHz readout rate). The CCD is reading out of
Port 2. The gain is set to 2.
Readout
Port
PORT 1
PORT 2
Bit
Depth
Pixel
Time
Current
Gain
Max
Gain
PARAM_SPDTAB_INDEX
PARAM_BIT
_DEPTH
PARAM_PIX
_TIME
PARAM_GAIN
_INDEX
PARAM_GAIN
_INDEX with ATTR_MAX
0
12
500
2
16
0
12
100
1
3
1
16
500
2
3
2
12
500
2
3
Entry
Table 4. Two Port Camera Example
It is the responsibility of the application program to remember variables associated with port and
speed selections. For example, the camera maintains one gain value. Changing this value will
change it for all port and speed choices. However, the application program may maintain gain
values for each setting and then write them to the camera when the user changes the current port or
speed. Read-only values, such as bit depth, may be read at time of open and saved in variables in
the application or may be read each time a user selection changes.
Once a selection is made, all settings remain in effect until the user resets them or until the camera
hardware is powered down or reset. If a camera has multiple speed entry numbers, you may choose
to view the settings located in the speed table. To view the speed table settings, call
pl_get_param with PARAM_SPDTAB_INDEX with the ATTR_MAX attribute to determine how
many speed entries are allowed on your camera. Then iterate through each choice to get the
associated information for that entry.
10
PVCAM Manual
Version 2.7
Frame Transfer
With a non-frame transfer CCD, the entire CCD is exposed, and the image read out before the CCD
is exposed again. A frame transfer CCD is divided into two areas: one for image collection and one
for image storage. After the CCD is exposed, the image is shifted to the storage array. A split clock
allows the CCD to expose the next frame of the image array while simultaneously reading out from
the storage array.
Since shifting an image to the storage array is many times faster than reading out the same image,
frame transfer speeds up many sequences.
In a standard frame transfer device, the storage array is usually masked and covers half the CCD.
With this standard configuration, the image in the storage array must be completely read out before
the next image is shifted into the storage array. Therefore, assuming that the exposure_time for
each image within a sequence is equal, the shortest possible exposure_time would be exactly
equal to the image readout time.
Image Array
Storage Array
Read out
Image shift to Storage Array
Interline
Interline (PMODE_INTERLINE) CCDs have a parallel register that has been subdivided into stripes so
that the opaque storage register fits between columns of pixels. The electronic image accumulates
in the exposed area of the parallel register. During CCD readout, the entire image is shifted under
the interline mask into a hidden shift register. Register readout then proceeds in normal CCD
fashion. Since the signal is transferred in microseconds, smearing will be undetectable for typical
exposures.
Read out
Storage Register
Image Array
Image shift to
Storage Registers
Kinetics
Kinetics (PMODE_KINETICS) is a special type of operation in which most of the CCD is
mechanically or optically masked, leaving a small section (window) open to light. This section is
Chapter 2: PVCAM, A High-Level C Library
11
then shifted under the mask very quickly. The defined clean cycles are used to keep charge from
accumulating on the array while it is waiting for a start exposure signal and after the data has been
readout of the array. The window size is set by PARAM_KIN_WIN_SIZE and must be at least 1 and less
than or equal to the PARAM_PAR_SIZE.
This mode of operation is available for full frame CCDs and requires a mechanical window.
Custom Chip
Normally, not all of the pixels in a CCD array are exposed and read out: a frame of “dummy” pixels
bounds the active area. These dummy pixels are usually masked and are not normally read out.
However, they could be read out by changing the chip definition. For example, in the case of the
EEV 576 × 384, the 576 active rows are preceded by one dummy row and followed by 2 dummy
rows. In addition, there are 12 dummy columns on one side of the active region and 13 dummy
columns on the other side. By changing the chip definition to increase the active area while
decreasing the dummy settings, the dummy cells would be read out. By doing so, one could
measure the dark charge with every readout. (Note that F.T. Dummies are chip-specific and are
dummy rows at the boundary of the masked and visible areas of a frame transfer device.)
It is also possible to increase image acquisition speed by reducing the size of the active area in the
definition. The result will be faster but lower resolution data acquisition. Operating in this mode
would ordinarily require that the chip be masked so that only the reduced active area is exposed. This
will prevent unwanted charge from spilling into the active area or being transferred to the shift
register.
Changing a chip definition requires that the custom chip feature is enabled via PARAM_CUSTOM_CHIP.
This allows the ATTR_ACCESS of the following parameters to change from ACC_READ_ONLY to
ACC_READ_WRITE: PARAM_PREMASK, PARAM_PRESCAN, PARAM_POSTMASK, PARAM_POSTSCAN,
PARAM_PAR_SIZE, PARAM_SER_SIZE, and PARAM_FTSCAN (for CCDS that have frame transfer
dummies between the active and the masked areas).
Custom Timing
Custom Timing (enabled via PARAM_CUSTOM_TIMING) allows you to change the parallel
(PARAM_PAR_SHIFT_TIME) and serial (PARAM_SER_SHIFT_TIME) shift rates for a CCD. Acceptable
shift times must be within the minimum value (ATTR_MIN) and the maximum value (ATTR_MAX),
and use the increment (ATTR_INCREMENT) or a multiple of the increment that falls within the
minimum and maximum values. Increments are in terms of nanoseconds.
Normally, the default timing parameter values have been determined to give the fastest possible
performance without compromising data acquisition performance.
Image Smear
If an image is shifted while the shutter is open, the charge that collects while the image is moving
makes the image look smeared. Smearing can occur in several situations: if the camera is set to read
out without closing the shutter, if the shutter is set to close too slowly, or in frame transfer
sequences where the shutter stays open while the image is shifted to the storage array.
12
PVCAM Manual
Version 2.7
In most frame transfer applications, the shutter opens before the sequence begins and closes after
the sequence ends. The charge gathered during the shift creates a smear across the image array.
Image Array
Storage Array
Image is exposed
Image Array
Storage Array
Image is shifted to storage array
Although the frame transfer time is usually only a few milliseconds, smearing cannot be eliminated
when the shutter is left open for the entire sequence. The higher the ratio of the exposure_time
to the frame transfer time, the brighter the image is in comparison to the pattern caused by
smearing. An exposure_time that is too long will saturate the pixels and cause the image to lose
all contrast.
Sequences
A sequence is a programmed series of exposures that is started by a single command. In the least
complex sequences, a setup is called, then the camera takes a series of exposures with a complete
readout between each exposure. In these simple sequences, all the variables in the setup apply to all
the exposures in the sequence. The diagram below illustrates a sequence of exposures taken as the
day passes.
Chapter 2: PVCAM, A High-Level C Library
13
In most camera modes, you must load a new setup into the camera if you want to change a variable
between sequences. PVCAM offers a few exceptions to this rule. Since several PVCAM exposure
modes ignore the setup exposure_time, an external trigger begins each sequence or each exposure in
the sequence. In one exposure mode, calling a command between sequences sets the exposure_time
for the next sequence.
Sequence Parameters IDs/Constants
When constructing a sequence, the following three items determine how the camera behaves before
reading out:
•
PARAM_CLEAR_MODE parameter id: Determines if and when the CCD is cleared of
charge.
•
BULB_MODE, FLASH_MODE, STROBED_MODE, TIMED_MODE,
TRIGGER_FIRST_MODE, or VARIABLE_ TIMED_MODE constant : Determines if a
program command or an external trigger starts and ends the exposure/nonexposure time
within a sequence.
•
PARAM_SHTR_OPEN_MODE parameter id: Determines if and when the shutter opens.
Although a single exposure may be considered a sequence of one, some options in triggering,
shuttering, and CCD clearing only apply to multiple image sequences.
Circular Buffer
Data
From Camera
Note: Because some cameras do not support circular buffer, use the
parameter id PARAM_CIRC_BUFFER with pl_get_param to see if the
system can perform circular buffer operations.
Data
Data
Data
1 Oldest
2
3
4 Latest
5
6
7
8
Circular buffers are a special case of sequences. In a sequence, you specify
the number of frames to acquire and allocate a buffer large enough to hold all
of the frames. Using a circular buffer allows you to acquire a continuous
sequence; the camera will continue to acquire frames until you decide to stop
it, rather than acquiring a specified number of frames. For a circular buffer,
Assumes 1 Mb frames
you allocate a buffer to hold a certain number of frames, and the data from
the camera is stored in the buffer sequentially until the end of the buffer is
reached. When the end is reached, the data is stored starting at the beginning of the buffer again,
and so on as shown in the above figure.
The image buffer used for a circular buffer is passed to pl_exp_start_cont. The buffer is either
allocated by your application or obtained from the driver as a preallocated contiguous block of
physical memory. The driver buffer pointer is retrieved using the pl_exp_get_driver_buffer
function. Data read out of the camera is stored in the designated circular buffer until it is retrieved by
the user's data processing routine, it is overwritten, or the buffer is filled. The selected circular buffer
mode determines whether or not buffer data can be overwritten before being retrieved by the
application.
When a circular buffer is running in CIRC_OVERWRITE mode, the frames in the buffer are filled as
data becomes available, regardless of whether the application has retrieved the data. This allows for
the fastest possible data display (on the host computer monitor) and is equivalent to the Princeton
Instruments Focus mode. If all frames in the buffer are filled before the application retrieves the
data, the oldest frame will be overwritten with new data. By fetching and displaying the most
14
PVCAM Manual
Version 2.7
recently stored frame, image data display can be virtually real-time. Briefly, this mode of circular
buffer is set up and runs as follows:
•
•
•
•
•
•
•
•
pl_exp_init_seq (): The camera is prepared to acquire and readout data.
pl_exp_setup_cont (circ_overwrite): The circular buffer mode is selected.
pl_exp_start_cont (): Continuous data acquisition is started.
Frames begin arriving in the buffer.
pl_exp_check_cont_status (): The status of the buffer is checked.
pl_exp_get_latest_frame (): If there are one or more frames of data, the most
recently stored frame is read out.
Data is processed (for example, the data is displayed).
The loop is repeated until continuous data acquisition is stopped with pl_exp_stop_cont (),
pl_exp_finish_seq (),and pl_exp_uninit_seq ().
When a circular buffer is running in CIRC_NO_OVERWRITE mode, the frames in the buffer are
filled as data becomes available until all frames are filled. This mode allows for the fastest possible
frame rate (with regard to data storage) with no skipping of frames and is equivalent to the
Princeton Instruments Nframe mode. If all frames in the buffer are filled before the application
retrieves the data, the latest frame will be lost because the oldest frame will not be overwritten.
Therefore, the user's routine must be able to read the data out of the buffer faster than the camera
can fill the buffer. Briefly, this mode of circular buffer is set up and runs as follows:
•
•
•
•
•
•
•
•
•
pl_exp_init_seq (): The camera is prepared to acquire and readout data.
pl_exp_setup_cont (circ_no_overwrite): The circular buffer mode is selected.
pl_exp_start_cont (): Continuous data acquisition is started.
Frames begin arriving in the buffer.
pl_exp_check_cont_status (): The status of the buffer is checked.
pl_exp_get_oldest_frame (): If there are one or more frames of data, the oldest frame is
read out.
Data is processed (for example, stored elsewhere).
pl_exp_unlock_oldest_frame (): The oldest frame is unlocked so it becomes
available for data storage.
The loop is repeated until the buffer fills up or continuous data acquisition is stopped with
pl_exp_stop_cont (), pl_exp_finish_seq (),and pl_exp_uninit_seq ().
Refer to Example 3: Circular Buffer in Chapter 8 for two examples of code for circular buffer
operation.
Chapter 2: PVCAM, A High-Level C Library
15
Clear Modes
Clearing removes charge from the CCD by clocking the charge to the serial register then directly to
ground. This process is much faster than a readout, because the charge does not go through the
readout node or the amplifier. Note that not all clearing modes are available for all cameras. Be
sure to check availability of a mode before attempting to set it.
The clear modes are described below:
•
CLEAR_NEVER: Don't ever clear the CCD. Useful for performing a readout after an
exposure has been aborted.
•
CLEAR_PRE_EXPOSURE: Before each exposure, clears the CCD the number of times
specified by the clear_cycles variable. This mode can be used in a sequence. It is most useful
when there is a considerable amount of time between exposures.
•
CLEAR_PRE_SEQUENCE: Before each sequence, clears the CCD the number of times
specified by the clear_cycles variable. If no sequence is set up, this mode behaves as if the
sequence has one exposure. The result is the same as using CLEAR_PRE_EXPOSURE.
•
CLEAR_POST_SEQUENCE: Clears continuously after the sequence ends. The camera
continues clearing until a new exposure is set up or started, the abort command is sent, the
speed entry number is changed, or the camera is reset.
•
CLEAR_PRE_POST_SEQUENCE: Clears clear_cycles times before each sequence and clears
continuously after the sequence ends. The camera continues clearing until a new exposure is
set up or started, the abort command is sent, the speed entry number is changed, or the
camera is reset.
•
CLEAR_PRE_EXPOSURE_POST_SEQ: Clears clear_cycles times before each exposure and
clears continuously after the sequence ends. The camera continues clearing until a new
exposure is set up or started, the abort command is sent, the speed entry number is changed,
or the camera is reset.
Normally during the idle period, the Camera Control Subsystem (CCS) parallel and serial clock
drivers revert to a low power state that saves both power and heat. When CLEAR_..._POST options are
used, the continuous clearing prevents these systems from entering low-power mode. This state
generates a small amount of additional heat in the electronics unit and the camera head.
The pl_exp_abort() function stops the data acquisition and the camera goes into the clean cycle.
Again, the CCD chip is continuously being cleaned.
Clear Modes decide when to clean the CCD arrays. However, since PI cameras always clean the
CCDs at idle times, Clear Modes do not apply to PI cameras and therefore the feature is not
available for PI cameras.
16
PVCAM Manual
Version 2.7
Exposure Modes
During sequences, the exposure mode determines how and when each exposure begins and ends:
TIMED_MODE
STROBED_MODE
VARIABLE_ TIMED_MODE
BULB_MODE
TRIGGER_FIRST_MODE
FLASH_MODE
In general, the settings in pl_exp_setup_seq apply to each exposure within a sequence. They
also apply to every sequence until the setup is reset. The only exceptions are in
VARIABLE_TIMED_MODE and BULB_MODE. These two modes ignore the exposure_time
parameter in setup, and rely on a function or trigger to determine the exposure time.
Every sequence has alternating periods of exposure and nonexposure time. During the time the CCD
is not exposing, the camera could be in several states, such as waiting for pl_exp_start_seq,
reading out, or performing continuous clearing. In the diagrams that follow, each exposure mode
shows the exposure time in white and the time between exposures in gray.
Exposure: TIMED_MODE
In TIMED_MODE, all settings are read from the setup parameters, making the duration of each
exposure time constant and the interval times between exposures constant. In this mode, every
sequence has the same settings.
The diagram below represents a sequence in TIMED_MODE.
Time in ms
0
50
100
150
200
Nonexposure Time
250
300
350
400
Exposure Time
Exposure: VARIABLE_TIMED_MODE
Use VARIABLE_TIMED_MODE when you want to change the exposure_time between sequences.
In VARIABLE_TIMED_MODE, all settings except exposure_time are read from the setup
parameters. The exposure_time must be set with parameter id PARAM_EXP_TIME. If you do not
call PARAM_EXP_TIME before the first sequence, a random time will be assigned. The camera will
not read the first exposure time from the exposure_time in setup, because this mode ignores the
exposure_time parameter.
Application example: A filter wheel is used to change the filter color between sequences. The
exposure time needed for the darkest filter saturates the pixels when lighter filters are used. The
diagram on the next page shows two sample sequences from this example.
Chapter 2: PVCAM, A High-Level C Library
Time in ms
0
50
100
150
200
250
Nonexposure Time
300
17
350
400
Exposure Time
The first sequence runs with a filter that uses exposure and nonexposure times that are equal. In the
second sequence, the exposure time is longer, but the time between exposures remains the same as
in the first sequence.
Exposure: TRIGGER_FIRST_MODE
Use TRIGGER_FIRST_MODE when you want an external trigger to signal the start of the sequence.
Time in ms
0
50
100
150
Nonexposure Time
200
250
300
350
400
Trigger Signal
Exposure Time
In TRIGGER_FIRST_MODE, pl_exp_start_seq starts the camera, which enters the clear mode
while it waits for a trigger signal. The black line in the diagram illustrates a trigger signal coming
from an external trigger source.
Once the outside event triggers the camera to start exposing, the sequence follows the conditions
generated in pl_exp_setup_seq. Note that all exposure times are equal, and the time intervals
between exposures are equal.
You must have an external trigger signal connected to your camera for TRIGGER_FIRST_MODE to
function. If your equipment fails to send a trigger signal, you can stop the sequence by calling
pl_exp_abort.
Note: If you do not use one of the CLEAR_PRE_EXPOSURE modes, the CCD will begin exposing
immediately after pl_exp_start_seq is called. Once the trigger is received, the CCD will
continue to expose for the exposure_time specified in pl_exp_setup_seq. In other words, the
first exposure in your sequence may have a longer exposure time than the subsequent exposures.
Exposure: STROBED_MODE
Use STROBED_MODE when you want an external trigger to start each exposure in the sequence.
Time in ms
0
50
100
Nonexposure Time
150
200
250
Exposure Time
300
350
400
Trigger Signal
18
PVCAM Manual
Version 2.7
In STROBED_MODE, pl_exp_start_seq starts the camera. The camera enters clear mode
while it waits for the first trigger signal to start the first exposure. As shown in the diagram above,
each new exposure waits for an external trigger signal. Notice that the intervals between exposures
can vary greatly, but the exposure times are constant.
You must have an external trigger signal connected to your camera for this mode to function. If your
equipment fails to send a trigger signal, you can stop the sequence by calling pl_exp_abort.
Application example: In a nature study of birds passing through a restricted area, the motion of
each bird sends a trigger signal to the camera. The camera exposes, reads out, and waits for the next
trigger signal. The result is an image of each bird as it crosses the camera's field of view.
Note: If you do not use one of the CLEAR_PRE_EXPOSURE modes, the CCD will begin exposing
immediately after pl_exp_start_seq is called. Once the trigger is received, the CCD will
continue to expose for the exposure_time specified in pl_exp_setup_seq. In other words, the
first exposure in your sequence may have a longer exposure time than the subsequent exposures.
Exposure: BULB_MODE
Use BULB_MODE, when you want an external trigger signal to control the beginning and end of
each exposure.
Time in ms
0
50
100
Nonexposure Time
150
200
250
Exposure Time
300
350
400
450
Trigger Signal
In BULB_MODE, pl_exp_start_seq calls the setup. The camera enters clear mode while it
waits for a true external trigger signal to start each exposure. The CCD continues to expose until a
false trigger signal ends the exposure. In the diagram above, the trigger signal line moves up to
represent a true trigger and down to represent a false trigger.
Notice that the exposure times and the intervals between exposures vary greatly. Since the true and
false signals determine exposure time, the exposure_time set in pl_exp_setup_seq is ignored.
You must have an external trigger signal connected to your camera for BULB_MODE to function. If
your equipment fails to send a trigger signal, you can stop the sequence by calling pl_exp_abort.
Note: If you do not use one of the CLEAR_PRE_EXPOSURE modes, the CCD exposes until
receiving a false trigger signal, then reads out. After reading out, the CCD exposes again without
clearing and waits for the true trigger. Once the external event causes a true trigger, the CCD
continues to expose until receiving a false trigger, then reads out. In other words, the CCD will
expose from the end of readout until the next false trigger.
Exposure: FLASH_MODE
Some PVCAM cameras include a flash port—several outside pins with a software-controllable
signal. Photometrics uses these pins to drive factory test fixturing. However, the signal can be used
to drive other equipment. Aside from the signal on the pins, FLASH_MODE is identical to
TIMED_MODE. Consult your camera hardware documentation to see flash port availability and
electrical specifications.
Chapter 2: PVCAM, A High-Level C Library
19
Open Delay, Close Delay
In order to ensure that the entire CCD is exposed for the specified exposure_time, the
mechanical limitations of the shutter must be considered. Open delay
(PARAM_SHTR_OPEN_DELAY), close delay (PARAM_SHTR_CLOSE_DELAY), and time units
(PARAM_SHTR_CLOSE_DELAY_UNIT)account for the time necessary for the shutter to open and
close. Remember that the camera is exposing while the shutter is opening and closing, so some
pixels are exposed longer than others.
Iris Shutter
An Iris shutter opens in an expanding circular pattern.
Barn Door Shutter
A Barn Door shutter slides across the exposure area.
If the shutter is still closing when the image shifts for a frame transfer or readout, the image will
smear. (See the section "Image Smear", page 11, for a more complete explanation on smearing.)
PARAM_SHTR_CLOSE_DELAY allows time for the shutter to close before the image shifts.
The default open and close delay values will vary depending on the brand of camera and the shutter
used. Open delay may be up to 15 milliseconds with a close delay of up to 30 milliseconds. Change
the default values only if you are using a shutter other than the shutter shipped with your camera. If
you are using a standard Photometrics or Princeton Instruments shutter, changing
PARAM_SHTR_OPEN_DELAY/CLOSE_DELAY default values will not increase the frame transfer
rate.
20
PVCAM Manual
Version 2.7
Shutter Control
The shutter open modes determine how the shutter in a camera behaves when a single exposure is
taken or when a sequence is run. Remember that the camera is exposing while the shutter is
opening. Because not all supported cameras have programmable shutter control, remember to
check for availability of a particular mode.
•
OPEN_PRE_EXPOSURE: Opens the shutter before every exposure, then closes the shutter
after the exposure is finished.
•
OPEN_PRE_SEQUENCE: Opens the shutter before the sequence begins, then closes the shutter
after the sequence is finished.
•
OPEN_PRE_TRIGGER: Opens the shutter, then clears or exposes (set in clear mode) until a
trigger signal starts the exposure.
•
OPEN_NEVER: Keeps shutter closed during the exposure. Used for dark exposures.
•
OPEN_NO_CHANGE: Sends no signals to open or close the shutter.
Exposure Loops
Within an exposure loop, the interaction of the exposure, clear, and shutter open modes determines
how the camera behaves during a sequence. In the following pages, sample command sequences
show how each exposure mode acts in combination with each clear and shutter open mode. As
mentioned above in "Shutter Control", not all supported cameras have programmable shutter
control, remember to check for availability of a particular mode.
Key
Description
ClearN
Clear CCD N times as specified in clear_cycles
OS
Open shutter and perform PARAM_SHTR_OPEN_DELAY
CS
Close shutter and perform PARAM_SHTR_CLOSE_DELAY
EXP
Expose CCD for exposure_time
I->S
Transfer image array to storage array (frame transfer)
Readout
Readout CCD (readout storage array for frame transfer)
WaitT
Wait until trigger
EXP Until notT
Expose CCD until trigger end (BULB_MODE)
Items in ITALICS repeat M times for a sequence of M exposures.
Items in BOLD are outside of the sequence loop.
EXPOSURE: TIMED_MODE
Chapter 2: PVCAM, A High-Level C Library
21
EXPOSURE: TIMED_MODE
Clear Mode
CLEAR_PRE_EXPOSURE
CLEAR_PRE_SEQUENCE
CLEAR_NEVER
Shutter Mode
Command Sequence
OPEN_PRE_EXPOSURE
ClearN, OS, EXP, CS, I->S, Readout
OPEN_PRE_SEQUENCE
OS , ClearN, EXP, I->S, Readout, CS
OPEN_PRE_TRIGGER
ClearN, OS, EXP, CS, I->S, Readout
OPEN_NO_CHANGE
ClearN, EXP, I->S, Readout
OPEN_NEVER
CS, ClearN, EXP, I->S, Readout
OPEN_PRE_EXPOSURE
ClearN,OS, EXP, CS, I->S, Readout
OPEN_PRE_SEQUENCE
OS, ClearN, EXP, I->S, Readout, CS
OPEN_PRE_TRIGGER
ClearN, OS, EXP, CS, I->S, Readout
OPEN_NO_CHANGE
ClearN, EXP, I->S, Readout
OPEN_NEVER
CS, ClearN, EXP, I->S, Readout
OPEN_PRE_EXPOSURE
OS, EXP, CS, I->S, Readout
OPEN_PRE_SEQUENCE
OS, EXP, I->S, Readout, CS
OPEN_PRE_TRIGGER
OS, EXP, CS, I->S, Readout
OPEN_NO_CHANGE
EXP, I->S, Readout
OPEN_NEVER
CS, EXP, I->S, Readout
Notes
Photometrics
only
Photometrics
only
EXPOSURE: TRIGGER_FIRST_MODE
Clear Mode
CLEAR_PRE_EXPOSURE
CLEAR_PRE_SEQUENCE
CLEAR_NEVER
Shutter Mode
Command Sequence
OPEN_PRE_EXPOSURE
EXP+WaitT, ClearN, OS, EXP, CS,
I->S, Readout
OPEN_PRE_SEQUENCE
OS, EXP+WaitT, ClearN, EXP, I->S,
Readout, CS
OPEN_PRE_TRIGGER
EXP+WaitT, OS, ClearN, EXP, CS,
I->S, Readout
OPEN_NO_CHANGE
EXP+WaitT, ClearN, EXP, I->S,
Readout
OPEN_NEVER
CS, EXP+WaitT, ClearN, EXP, I->S,
Readout
OPEN_PRE_EXPOSURE
Clear+WaitT, ClearN, OS, EXP, CS,
I->S, Readout
OPEN_PRE_SEQUENCE
OS, Clear+WaitT, EXP, I->S,
Readout, CS
OPEN_PRE_TRIGGER
Clear+WaitT, OS, EXP, CS, I->S,
Readout
OPEN_NO_CHANGE
Clear+WaitT, EXP, I->S, Readout
OPEN_NEVER
CS, Clear+WaitT, EXP, I->S, Readout
OPEN_PRE_EXPOSURE
EXP+WaitT, ClearN, OS, EXP, CS,
I->S, Readout
OPEN_PRE_SEQUENCE
OS, EXP+WaitT, EXP, I->S, Readout,
CS
Notes
Photometrics
only
Photometrics
only
22
PVCAM Manual
Version 2.7
EXPOSURE: TRIGGER_FIRST_MODE
Clear Mode
Shutter Mode
Command Sequence
OPEN_PRE_TRIGGER
EXP+WaitT, OS, EXP, CS, I->S,
Readout
OPEN_NO_CHANGE
EXP+WaitT, EXP, I->S, Readout
OPEN_NEVER
CS, EXP+WaitT, EXP, I->S, Readout
Notes
EXPOSURE: STROBED_MODE
Clear Mode
CLEAR_PRE_EXPOSURE
CLEAR_PRE_SEQUENCE
CLEAR_NEVER
Shutter Mode
Command Sequence
OPEN_PRE_EXPOSURE
Clear+WaitT, OS, EXP, CS, I->S,
Readout
OPEN_PRE_SEQUENCE
OS, Clear+WaitT, EXP, I->S, Readout,
CS
OPEN_PRE_TRIGGER
OS, Clear+WaitT, EXP, CS, I->S,
Readout
OPEN_NO_CHANGE
Clear+WaitT, EXP, I->S, Readout
OPEN_NEVER
CS, Clear+WaitT, EXP, I->S, Readout
OPEN_PRE_EXPOSURE
ClearN, EXP+WaitT, OS, EXP, CS,
I->S, Readout
OPEN_PRE_SEQUENCE
OS, ClearN, EXP+WaitT, EXP, I->S,
Readout, CS
OPEN_PRE_TRIGGER
ClearN, OS, EXP+WaitT, EXP, CS,
I->S, Readout
OPEN_NO_CHANGE
ClearN, EXP+WaitT, EXP, I->S,
Readout
OPEN_NEVER
CS, ClearN, EXP+WaitT, EXP, I->S,
Readout
OPEN_PRE_EXPOSURE
EXP+WaitT, OS, EXP, CS, I->S,
Readout
OPEN_PRE_SEQUENCE
OS, EXP+WaitT, EXP, I->S, Readout,
CS
OPEN_PRE_TRIGGER
OS, EXP+WaitT, EXP, CS, I->S,
Readout
OPEN_NO_CHANGE
EXP+WaitT, EXP, I->S, Readout
OPEN_NEVER
CS, EXP+WaitT, EXP, I->S, Readout
Notes
Uses
Continuous
Cleans
Photometrics
only
Chapter 2: PVCAM, A High-Level C Library
23
EXPOSURE: BULB_MODE
Clear Mode
CLEAR_PRE_EXPOSURE
CLEAR_PRE_SEQUENCE
CLEAR_NEVER
Shutter Mode
Command Sequence
OPEN_PRE_EXPOSURE
Clear+WaitT, OS, EXP Until notT,
CS, I->S, Readout
OPEN_PRE_SEQUENCE
OS, Clear+WaitT, EXP Until notT,
I->S, Readout, CS
OPEN_PRE_TRIGGER
OS, Clear+WaitT, EXP Until notT,
CS, I->S, Readout
OPEN_NO_CHANGE
Clear+WaitT, EXP Until notT, I->S,
Readout
OPEN_NEVER
CS, Clear+WaitT, EXP Until notT,
I->S, Readout
OPEN_PRE_EXPOSURE
ClearN, EXP+WaitT, OS, EXP Until
notT, CS, I->S, Readout
OPEN_PRE_SEQUENCE
OS, ClearN, EXP+WaitT, EXP Until
notT,
I->S, Readout, CS
OPEN_PRE_TRIGGER
ClearN, OS, EXP+WaitT, EXP Until
notT, CS, I->S, Readout
OPEN_NO_CHANGE
ClearN, EXP+WaitT, EXP Until notT, I>S, Readout
OPEN_NEVER
CS, ClearN, EXP+WaitT, EXP Until
notT, I->S, Readout
OPEN_PRE_EXPOSURE
EXP+WaitT, OS, EXP Until notT, CS,
I->S, Readout
OPEN_PRE_SEQUENCE
OS, EXP+WaitT, EXP Until notT,
I->S, Readout, CS
OPEN_PRE_TRIGGER
OS, EXP+WaitT, EXP Until notT, CS,
I->S, Readout
OPEN_NO_CHANGE
EXP+WaitT, EXP Until notT, I->S,
Readout
OPEN_NEVER
CS, EXP+WaitT, EXP Until notT,
I->S, Readout
Notes
Photometrics
only
Photometrics
only
Photometrics
only
24
PVCAM Manual
Version 2.7
Image Buffers
When exposures include multiple images and complex sequences, you may choose to store the
images in a buffer. PVCAM has a number of buffer routines that handle memory allocation and
freeing. The following list describes images you may choose to store in a buffer.
•
Full CCD: A single exposure where the entire CCD is treated as one region and image data
are collected over the full CCD. All the data are stored in a single buffer.
•
Single Exposure, Multiple Images: A single exposure with multiple regions. The data are
stored in several image arrays that are stored inside a single buffer.
•
Sequences: A series of exposures with identical regions. The data are stored in several image
arrays that are stored inside a single buffer.
•
Multiple Exposures, Multiple Images: A series of exposures with multiple regions. Each
exposure must have identical regions. The data are stored in several image arrays that are
stored inside a single buffer.
Class 4 places the following constraints on data stored in buffers:
•
All exposures in a buffer must have the same set of images (the size, position, and binning
must match).
•
All data in a buffer must be at the same bit depth (16-bit signed, 16- bit unsigned, 32-bit
signed, and so forth.)
•
All data in an image are stored in a standard C, two-dimensional array, with the second
subscript varying most rapidly.
Chapter 2: PVCAM, A High-Level C Library
25
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 processing time:
•
Don’t use a buffer. The data are collected in a user-specified pixel stream at maximum
efficiency (see pl_exp_start_seq). As discussed in "Data Array", this array can be
accessed directly. However, when multiple regions are collected, the stream becomes more
complex. If the regions overlap in the serial direction, the data from one region are
interleaved with the data from another region.
•
Use a buffer. If the data are in multiple regions, pl_exp_finish_seq decodes the
pixel_stream data into the regions. Once decoded, each region can be retrieved as a
simple array (see "Data Array"). Even though it takes extra time to decode the data and load
the buffer, retrieving the data is simple.
•
Defer decoding. The original call to pl_exp_setup_seq sets up internal structures used to
decode pixel_stream into a buffer structure. However, pl_exp_finish_seq does not
need to be called immediately. As long as the camera (and library) remain open, and
pl_exp_setup_seq is not called with a new setup, the decoding structures remain valid.
This allows a program to collect data quickly, then decode the data when more time is
available. Of course, this is impossible if users must be given immediate feedback.
Source Code Examples
Refer to Chapter 8, pages 111-122, for code examples.
26
PVCAM Manual
This page intentionally left blank.
Version 2.7
Chapter 3:
Camera Communications (Class 0)
Introduction
The functions in this category provide a pipeline for bidirectional communications. The table below
lists the current Class 0 functions, and the "Class 0 Functions" section provides detailed
descriptions of each. If the Class 0 functions you are interested in are not listed below, check
"Appendix B: Obsolete Functions". The Class 0 functions that have been made obsolete now have
equivalent pl_get_param and pl_set_param functions. For more information about the
pl_get_param and pl_set_param parameter ids, refer to "Chapter 5:Configuration/Setup
(Class 2)", starting on page 45.
List of Available Class 0 Functions
Library
Camera
pl_pvcam_init
pl_cam_check
pl_pvcam_uninit
pl_cam_close
pl_pvcam_get_ver
pl_cam_get_diags
pl_cam_get_name
Device Driver
pl_ddi_get_ver
pl_cam_get_total
pl_cam_open
List of Available Class 0 Parameter IDs
The following are available Class 0 parameters used with pl_get_param(), pl_set_param(),
pl_get_enum_param(), and pl_enum_str_length() functions specified in Chapter 5.
PARAM_DD_INFO
PARAM_DD_TIMEOUT
PARAM_DD_INFO_LENGTH
PARAM_DD_VERSION
PARAM_DD_RETRIES
27
28
PVCAM Manual
Version 2.7
Class 0 Functions
PVCAM
Class 0: Camera Communications
pl_cam_check(0)
NAME
pl_cam_check — fails if hcam is not the handle of an open camera.
SYNOPSIS
rs_bool
pl_cam_check(int16 hcam)
DESCRIPTION
This is a fast check, used internally by many other functions before they access
hardware. This function checks whether the input handle, hcam, refers to an open
camera.
RETURN VALUE
TRUE for a valid handle, FALSE for an invalid handle.
SEE ALSO
pl_cam_open(0), pl_cam_close(0)
NOTES
Since this function is a frequent call, it is designed to be highly efficient. It does
not access hardware, it checks the internal state tables that are set by
pl_cam_open and pl_cam_close.
Chapter 3: Camera Communications (Class 0)
29
PVCAM
Class 0: Camera Communications
pl_cam_close(0)
NAME
pl_cam_close — frees the current camera, prepares it for power-down.
SYNOPSIS
rs_bool
pl_cam_close(int16 hcam)
DESCRIPTION
This has two effects. First, it removes the listed camera from the reserved list,
allowing other users to open and use the hardware. Second, it performs all
cleanup, close-down, and shutdown preparations needed by the hardware. A
camera can only be closed if it was previously opened; hcam must be a valid
camera handle.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_cam_open(0),pl_pvcam_init(0),pl_pvcam_uninit(0)
NOTES
pl_pvcam_uninit automatically calls a pl_cam_close on all cameras opened
by the current user.
30
PVCAM Manual
Version 2.7
PVCAM
Class 0: Camera Communications
pl_cam_get_diags(0)
NAME
pl_cam_get_diags — fails and returns an error if there are any problems with
the camera.
SYNOPSIS
rs_bool
pl_cam_get_diags(int16 hcam)
DESCRIPTION
All functions that open or reset the camera perform a short set of checks and
diagnostics. The error codes set in these diagnostics are stored in a table. When
hcam is a valid camera handle, pl_cam_get_diags (called immediately after
pl_cam_open) reads the table and reports any critical error condition by
returning FALSE.
Both critical and noncritical subsystem error codes are set, although only critical
subsystem failures return a FALSE. Critical subsystems are defined as systems
that, if they fail, may prevent the camera from acquiring or reading out an image.
Critical and noncritical errors are listed in pl_error_code .
RETURN VALUE
FALSE indicates that a critical subsystem is not working, and therefore the
camera may not be able to acquire or read out an image. TRUE indicates that no
error codes have been set for critical subsystems, but there may be error codes
set for noncritical subsystems. Noncritical subsystem errors are considered
warnings. Critical and noncritical errors are listed in pl_error_code .
SEE ALSO
pl_cam_open(0)
NOTES
This function call is designed to be fast, therefore to ensure that camera hardware
is attached and functional, pl_cam_get_diags can be called before every
exposure.
Chapter 3: Camera Communications (Class 0)
31
PVCAM
Class 0: Camera Communications
pl_cam_get_name(0)
NAME
pl_cam_get_name — returns the name of a camera.
SYNOPSIS
rs_bool
pl_cam_get_name(int16 cam_num,char_ptr cam_name)
DESCRIPTION
This function allows a user to learn the string identifier associated with every
camera on the current system. This is a companion to the pl_cam_get_total
function. Cam_num input can run from 0 to ( total_cams - 1), inclusive. The
user must pass in a string that is at least CAM_NAME_LEN characters long;
pl_cam_get_name then fills that string with an appropriate null-terminated
string. Cam_name can be passed directly into the pl_cam_open function. It has
no other use, aside from providing a brief description of the camera.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_cam_get_total(0),pl_cam_open(0),pl_cam_close(0)
NOTES
This call reports the names of all cameras on the system, even if all the cameras
are not available. If the hardware is turned off, or if another user has a camera
open, the camera name is reported, but is not available.
Pl_cam_get_name returns a name, and pl_cam_open gives information on
availability of that camera. This function actually searches for all device drivers
on the system, without checking hardware. To build a complete list of every
camera on the system, it is necessary to cycle through all entries, as shown
below:
int total_cameras;
char cam_name[CAM_NAME_LEN];
…
pl_cam_get_total(&total_cameras );
for( I=0; I
(&pFrame)))return -1;
if(!pl_exp_unravel(hCam, 0, pFrame, 2, r,
pUnraveledData)) return -1;
if(!pl_exp_unlock_oldest_frame(hCam)) return -1;
--numFrames;
}
}
while( numFrames );
88
PVCAM Manual
Version 2.7
PVCAM
Class 3: Data Acquisition
NAME
pl_io_clear_script_control - Clears the current setup for control of
the available I/O lines within a camera script.
SYNOPSIS
rs_bool
pl_io_clear_script_control(int16 hcam)
DESCRIPTION
This function allows the application program to clear the current setup for
control of the available I/O lines within the script. This allows the user to enter a
new setup for these lines.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_io_script_control(3)
NOTES
pl_io_clear_script_control(3)
Chapter 6: Data Acquisition (Class 3)
89
PVCAM
Class 3: Data Acquisition
pl_io_script_control(3)
NAME
pl_io_script_control - Defines control of an I/O line from within a
camera script.
SYNOPSIS
rs_bool
pl_io_script_control(int16 hcam, uns16 addr, flt64 state,
uns32 location)
DESCRIPTION
This function allows the application program to define control of the available
I/O lines from within a script. This allows for more precise control of external
devices. For example, the application could request that a linear stage be indexed
immediately after integration, instead of waiting until after the data is read out,
the shutter is closed, etc. addr specifies which I/O address to control. state
specifies the desired setting for the address being controlled.
state has different meanings depending on the I/O type:
IO_TYPE_TTL
The bit pattern written to this address.
IO_TYPE_DAC
The value of the desired analog output written to the DAC
at this address.
location can be set to the following values:
SCR_PRE_OPEN SHTR
SCR_POST_OPEN_SHTR
SCR_PRE_FLASH
SCR_POST_FLASH
SCR_PRE_INTEGRATE
SCR_POST_INTEGRATE
SCR_PRE_READOUT
SCR_POST_READOUT
SCR_PRE_CLOSE_SHTR
SCR_POST_CLOSE_SHTR
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_io_clear_script_control(3)
NOTES
90
PVCAM Manual
Version 2.7
Class 3 Parameter IDs
Note: Camera Dependent indicates that this parameter or function is not available to all
Roper Scientific cameras. If a parameter or function is marked Camera Dependent, an
ATTR_AVAIL should be called to see if the camera supports it.
Class 3 Parameter ID
Description
PARAM_BOF_EOF_CLR
Clears the BOF-EOF count when a pl_set_param is
performed. This is a write-only parameter.
Camera Dependent
Datatype: rs_bool
PARAM_BOF_EOF_COUNT
Returns the Begin-Of-Frame and/or End-Of-Frame
count. BOF_EOF counting is enabled and configured
with PARAM_BOF_EOF_ENABLE.
Camera Dependent
Datatype: uns32
PARAM_BOF_EOF_ENABLE
Camera Dependent
Enables and configures the BOF_EOF interrupts.
Possible values are:
NO_FRAME_IRQS
BEGIN_FRAME_IRQS
END_FRAME_IRQS
BEGIN_END_FRAME_IRQS
Datatype: enum
PARAM_CIRC_BUFFER
Tests to see if the hardware/software can perform
circular buffer. When a TRUE is returned, the circular
buffer function can be used.
Datatype: rs_bool
PARAM_EXP_MIN_TIME
Gets the minimum effective exposure time that can be
set for the camera. For example, the exposure time
may be limited by the required overhead for shifting the
data through the array. This minimum time will be a
floating point value, in seconds. Note that the
minimum exposure time returned by this function will
be greater than zero; any camera can provide a
minimum exposure time of zero.
Datatype: flt64
PARAM_EXP_RES
Gets the resolution for the current resolution index, as
described for PARAM_EXP_RES_INDEX. This value is
an enumerated type, representing the resolution.
Possible values are :
EXP_RES_ONE_MILLISEC
EXP_RES_ONE_MICROSEC
EXP_RES_ONE_SEC
Datatype: enum
Chapter 6: Data Acquisition (Class 3)
Class 3 Parameter ID
PARAM_EXP_RES_INDEX
91
Description
Gets and sets the index into the exposure resolution
table for the camera. The table contains the resolutions
supported by the camera. The value at this index
(PARAM_EXP_RES) is an enumerated type as given by
PARAM_EXP_RES. The number of supported resolutions
can be obtained by using the ATTR_MIN and
ATTR_MAX attributes with the
PARAM_EXP_RES_INDEX parameter.
Datatype: uns16
PARAM_EXP_TIME
This is used to examine and change the exposure time
in VARIABLE_TIMED_MODE.
Datatype: uns16
PARAM_HW_AUTOSTOP
Camera Dependent
Sets the number of frames to acquire synchronously
into a register for PI brand cameras. At the data
acquisition, the hardware counts the number of frames
transferred, then stops the acquisition when it reaches
the count set with PARAM_HW_AUTOSTOP. The
maximum number the application can set is 254. If an
application needs more than 254, it must set it to
ZERO, i.e., a continuous acquisition and issue the
STOP command manually to halt the acquisition. For
focusing mode, an application should set this parameter
to ZERO.
Datatype: int16
92
PVCAM Manual
This page intentionally left blank.
Version 2.7
Chapter 7:
Buffer Manipulation (Class 4)
Introduction
Class 4 places the following constraints on data stored in buffers:
•
All exposures in a buffer must have the same set of images (the size, position, and binning
must match).
•
All data in a buffer must be at the same bit depth (16-bit signed, 16-bit unsigned, 32-bit
signed, etc.).
•
All data in an image is stored in a standard C two-dimensional array, with the second
subscript varying most rapidly.
In addition to the image data itself, a significant amount of auxiliary information is recorded in a
buffer. There is no facility for setting the information (besides setting the date), but you can read the
information with the get_ functions in the Buffer Information category below.
List of Available Class 4 Functions
The buffer manipulation functions are divided into three categories: Buffer Information, Allocation
and Saving, and Initialization.
Buffer Information
Allocation and Saving
pl_buf_get_bits
pl_buf_alloc
pl_buf_get_exp_date
pl_buf_free
pl_buf_get_exp_time
pl_buf_get_exp_total
pl_buf_get_img_bin
Initialization
pl_buf_get_img_handle
pl_buf_init
pl_buf_get_img_ofs
pl_buf_uninit
pl_buf_get_img_ptr
pl_buf_get_img_size
pl_buf_get_img_total
pl_buf_get_size
pl_buf_set_exp_date
93
94
PVCAM Manual
Version 2.7
New Constants
Several new constants are used to indicate the bit depth of image data. Since these are constants, not
system-dependent types, they are defined in pvcam.h:
PRECISION_INT8
This is 8-bit, signed data, in the range -128 to 127.
PRECISION_UNS8
This is 8-bit, unsigned data, in the range 0 to 255.
PRECISION_INT16
This is 16-bit, signed data, in the range -32768 to 32767.
PRECISION_UNS16
This is 16-bit, unsigned data, in the range 0 to 65535.
PRECISION_INT32
This is 32-bit, signed data, in the range -2,147,483,648 to
+2,147,483,647.
PRECISION_UNS32
This is 32-bit, unsigned data, in the range 0 to 4 GB-1.
Image Handles and Pointers
An image handle specifies the image. Like camera handles (hcam) and buffer handles (hbuf), an
image handle (himg) is an integer that is an index into a table kept by the PVCAM library. The
image handle, usually having the variable name himg, specifies the source buffer, exposure
number, and image number. If that buffer is freed, the handle becomes invalid, causing the table
entry to clear and be freed for new assignment. The handle for any image can be obtained through
pl_buf_get_img_handle.
A slightly different item is an image pointer. Internally, each image is organized as a flat twodimensional array with the following organization:
i0,j0 i0,j1 i0,j2 i0,j3 .... i0,j(j_size-1)i1,j0 i1, j1 i1,
j2 .... i(i_size-1),j(j_size-1)
In other words, this is a standard C two-dimensional array, with the second subscript varying most
rapidly. Immediately after creation, the j dimension is equivalent to the serial direction of the CCD,
while the i dimension is equivalent to the parallel direction. As processing may quickly blur this
relationship, the image buffers are presented with the more neutral i, j scheme instead of the
concepts serial and parallel.
The pl_buf_get_img_ptr function returns the address of element 0 of this array. Since
alignment depends on both the current operating system and the current bit depth, a void pointer is
returned. The user is responsible for the details of alignment and array organization.
In addition, no information is given concerning the data that follows the last element. This data may
be a following image, a following exposure, buffer header information, or operating system
memory. In other words, as in normal C memory usage, you are not prevented from writing past the
end of affected memory, but this may have unpredictable consequences.
Chapter 7: Buffer Manipulation (Class 4)
95
Class 4 Functions
PVCAM
Class 4: Buffer Manipulation
pl_buf_alloc(4)
NAME
pl_buf_alloc — allocates a buffer based on the current exposure setup.
SYNOPSIS
rs_bool
pl_buf_alloc(int16_ptr hbuf,int16 exp_total,int16
bit_depth,int16 rgn_total,rgn_const_ptr
rgn_array)
DESCRIPTION
This routine examines the region definition array pointed to by rgn_array to
determine the memory required to store the images from a single exposure. This
routine takes this array as a template for each exposure, and then allows the user
to specify the number of exposures in exp_total and the amount of storage per
pixel in bit_depth. bit_depth must use one of the following constants:
PRECISION_INT8, PRECISION_UNS8, PRECISION_INT16,
PRECISION_UNS16, PRECISION_INT32, and PRECISION_UNS32.
With this information, enough memory is allocated to hold the data from the set
of exposures. A handle to this buffer is passed back in hbuf.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_free(4),pl_buf_get_bits(4)
NOTES
When using this function, the definitions must match the region definitions in the
exposure setup, otherwise memory may be corrupted. If the region definition
changes, the buffer must be freed, and another buffer is allocated. Note that
bit_depth must be equal to one of the PRECISION_ constants as described at
the start of this section.
96
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
pl_buf_free(4)
NAME
pl_buf_free — frees the memory and handle used by a buffer.
SYNOPSIS
rs_bool
pl_buf_free(int16 hbuf)
DESCRIPTION
This routine frees the memory associated with hbuf. The memory is released
and the buffer handle becomes invalid.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_copy(4),pl_buf_load(4)
NOTES
Although the memory is freed, garbage collection is another issue. Many small
buffers may fragment memory, even if most of them are later freed. Garbage
collection is a system-dependent operation.
Chapter 7: Buffer Manipulation (Class 4)
97
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_bits(4)
NAME
pl_buf_get_bits — returns the buffer precision.
SYNOPSIS
rs_bool
pl_buf_get_bits(int16 hbuf,int16_ptr bit_depth)
DESCRIPTION
Every exposure and every image in a buffer must be at the same bit depth. This
function returns the depth for the images in hbuf. The parameter bit_depth
will be set to one of the following constants (defined in pvcam.h):
PRECISION_INT16
PRECISION_UNS16
PRECISION_INT32
Notice that these use the standard PVCAM types (int16, uns16, int32)
capitalized with the word PRECISION_ added.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_change_bits(4)
NOTES
98
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_exp_date(4)
NAME
pl_buf_get_exp_date — returns when a picture was taken.
SYNOPSIS
rs_bool
pl_buf_get_exp_date(int16 hbuf,int16 exp_num,int16_ptr
year,uns8_ptr month,uns8_ptr
day,uns8_ptr hour,uns8_ptr min,
uns8_ptr sec,uns16_ptr msec)
DESCRIPTION
This returns the time when the specified exposure was decoded. The format is:
Year
current year (i.e. , 2002)
month
1-12 (January through December)
day
1-31 (day number in the current month)
hour
0-23 (24-hour format)
min
0-59
sec
0-59
msec
0-999 milliseconds
To get a time for the entire buffer, it is usually adequate to examine the time for
exp_num 0, but, depending on the sequence and timing parameters, successive
exposures may be taken hours or even days later. To examine the exact exposure
time for any successive exposure in the sequence, merely specify a different
exp_num. The exposure end time may be obtained by adding the exposure
duration, obtained from the pl_buf_get_exp_time function.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_set_exp_date(4),pl_buf_get_exp_time(4),
pl_do_exp(3)
KNOWN BUGS
If the host computer clock is inaccurate, the time recorded will also be
inaccurate. Although most clocks are not accurate to a millisecond, the recorded
time should help differentiate between the exposures in a fast sequence.
Impossible time values (all 0, for example) usually indicate that the start time
was never set.
Chapter 7: Buffer Manipulation (Class 4)
99
PVCAM
Class 4: Buffer Manipulation
NAME
pl_buf_get_exp_time — returns exposure duration.
SYNOPSIS
rs_bool
pl_buf_get_exp_time(int16 hbuf,int16 exp_num,uns32_ptr
exp_msec)
DESCRIPTION
This returns the exposure duration in milliseconds, in the parameter exp_msec.
In most cases, the timing for the first exposure is identical for all exposures. In
BULB_MODE, however, the exposure time is unknown and can be adjusted for
every exposure. This allows the actual time to be read for the individual
exposures, by specifying the exposure number in exp_num (which is zeroindexed).
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_exp_date(4)
NOTES
pl_buf_get_exp_time(4)
100
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
NAME
pl_buf_get_exp_total — returns number of exposures in the buffer.
SYNOPSIS
rs_bool
pl_buf_get_exp_total(int16 hbuf,int16_ptr total_exps)
DESCRIPTION
This returns the number of exposures in the specified buffer, inside the variable
totl_exps. When referring to exposures by number, the first exposure will be
exposure number 0 (in typical C fashion). Therefore, the highest allowable
exposure number is totl_exps-1.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_img_total(4),pl_buf_append_exp(4)
NOTES
pl_buf_get_exp_total(4)
Chapter 7: Buffer Manipulation (Class 4)
101
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_img_bin(4)
NAME
pl_buf_get_img_bin — returns binning factors for the image.
SYNOPSIS
rs_bool
pl_buf_get_img_bin(int16 himg,int16_ptr ibin,int16_ptr
jbin)
DESCRIPTION
Default binning is ibin=1, jbin=1 (no binning, 1 CCD pixel becomes one
image pixel). Binning is set when a buffer is created. This function reports on the
binning that was used during acquisition, for the image indicated by himg.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_img_size(4)
NOTES
It is assumed that the binning is identical for each exposure. In other words, each
image in an exposure has its own binning values, but this information is only
entered once; it is not repeated for every exposure in the buffer. The value for
exposure 0 will always be identical to the value for every other exposure.
This is usually a safe assumption, but a user might use functions like
pl_buf_get_img_ptr to insert images that fit, but were taken under radically
different conditions, including different binning. In such a case, the value
reported for binning will not change, but it will no longer be accurate. It then
becomes the user's responsibility to keep track of the binning.
102
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_img_handle(4)
NAME
pl_buf_get_img_handle — obtains handle that refers to a single image in
buffer.
SYNOPSIS
rs_bool
pl_buf_get_img_handle(int16 hbuf,int16 exp_num,int16
img_num,int16_ptr himg )
DESCRIPTION
The image handle, himg, is a special handle that is used by the other image
functions and many higher analysis functions. The handle is a shorthand method
for referring to this image. It specifies the buffer handle, hbuf, the exposure
number, exp_num, and the image number img_num. In most cases, this is an
extremely fast call. It merely fills in table values, assigns a handle, and returns.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_img_ptr(4)
NOTES
A pointer to the data in this image is a completely different thing. This address is
given by the function pl_buf_get_img_ptr, which requires an image handle
as input. In general, the handle is useful to other PVCAM functions, while the
address is useful to programmers who require direct access to the pixel stream.
Many of the image definition factors: size, offset, and binning, are assumed to be
the same across all exposures in the buffer. In other words, the parameters
reported for img_num in exposure 0 are identical to the parameters reported for
img_num in every exposure.
Note that both exp_num and img_num are zero-indexed.
Chapter 7: Buffer Manipulation (Class 4)
103
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_img_ofs(4)
NAME
pl_buf_get_img_ofs
SYNOPSIS
rs_bool
pl_buf_get_img_ofs(int16 himg,int16_ptr s_ofs,int16_ptr
p_ofs)
DESCRIPTION
Pixel coordinates in an image begin at 0,0, despite its original position on the
CCD. The offset allows that original position to be recreated. The original
coordinates are saved in the offset, so that:
— returns offset position of the image.
s_ofs = s_offset = s1(starting serial position)
p_ofs = p_offset = p1(starting parallel position)
Each exposure in a sequence shares the same setup, therefore only the image
number (specified through himg) affects the reported offset. The exposure
number (also specified through himg) has no effect.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
NOTES
It is assumed that the offset is identical for each exposure. In other words, each
image has its own offset values, but this information is only entered once; it is
not repeated for every exposure in the buffer. The value reported for exposure 0
will always be identical to the value reported for every other exposure.
This is usually a safe assumption, but a user might use the image address and
direct access to insert images that fit, but were taken under radically different
conditions, including different offset. In such a case, the value reported for offset
will not change, but it will no longer be accurate. It then becomes the user's
responsibility to keep track of the offset.
104
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
NAME
pl_buf_get_img_ptr — returns the address of an image in the data buffer.
SYNOPSIS
rs_bool
pl_buf_get_img_ptr(int16 himg,void_ptr_ptr img_addr)
DESCRIPTION
This requires an image handle as input. Given that input, this function returns the
address of the first data element inside that image. The user can then directly
manipulate or rewrite the data, as desired. It allows optimum efficiency for data
manipulation, while still staying inside the PVCAM image buffer structure. The
address is returned in img_addr, which is defined as a pointer to type void. A
void pointer must be used, since alignment may vary from buffer to buffer. The
user is responsible for knowing the word size and indexing conventions, based
on the bit_depth, i_size, and j_size of the image.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_img_handle(4)
NOTES
pl_buf_get_img_ptr(4)
Chapter 7: Buffer Manipulation (Class 4)
105
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_img_size(4)
NAME
pl_buf_get_img_size — returns number of pixels in region.
SYNOPSIS
rs_bool
pl_buf_get_img_size(int16 himg,int16_ptr i_size, int16_ptr
j_size)
DESCRIPTION
This examines the image specified by the image handle himg, and determines
the i and j dimensions. The sizes are returned in I_size and j_size in pixels.
Since the pixel addresses begin with 0 (following typical C conventions), the
following relationship is true:
i_maximum_element_num = i_size - 1
j_maximum_element_num = j_size - 1
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_img_handle(4)
NOTES
This size is not necessarily the same as the number of pixels exposed on the
CCD. If the region was binned, the CCD area may have had many more pixels
than the final data set.
The set of images must be the same for every exposure in the buffer. For
example, image 3, exposure 0 must have the same size (and offset and binning)
as image 3, exposure 2. The sizes reported for the images in exposure 0 will
always be identical to the sizes reported for every other exposure.
106
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_img_total(4)
NAME
pl_buf_get_img_total — returns number of images in each exposure.
SYNOPSIS
rs_bool
pl_buf_get_img_total(int16 hbuf,int16_ptr img_total)
DESCRIPTION
This returns the number of images in the first exposure. Every exposure in the
same buffer will have exactly this many images, no more, no less. When
referring to images by number, counting begins at 0 (in typical C fashion), so the
highest allowed image number is actually img_total-1.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_exp_total(4),pl_buf_get_img_ofs(4),
pl_buf_get_img_size(4)
NOTES
Every exposure in the buffer must have exactly this many images.
Chapter 7: Buffer Manipulation (Class 4)
107
PVCAM
Class 4: Buffer Manipulation
pl_buf_get_size(4)
NAME
pl_buf_get_size — returns size of buffer, in bytes.
SYNOPSIS
rs_bool
pl_buf_get_size(int16 hbuf,uns32_ptr buf_size)
DESCRIPTION
This returns the size of a buffer, in bytes, inside the variable buf_size. This
value is useful when memory or disk space is tight, before performing operations
such as pl_buf_copy.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
NOTES
Buffer size can be estimated if you know the bit depth, number of exposures, and
the size of each image. This isn't completely accurate, though, since other
information is stored in a buffer: the exposure time and date, exposure duration,
size and offset values, etc.
108
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
pl_buf_set_exp_date(4)
NAME
pl_buf_set_exp_date — (re)writes the time that this picture was taken.
SYNOPSIS
rs_bool
pl_buf_set_exp_date(int16 hbuf,int16 exp_num,int16
year,uns8 day,uns8 hour,uns8 min,uns8
sec,uns16 msec)
DESCRIPTION
This allows the time of any exposure to be recorded or rewritten. This should be
the time when the exposure started. The format is:
Year
current year (i.e. 1995)
month
1-12 (January through December)
day
1-31 (day number in the current month)
hour
0-23 (24-hour format)
min
0-59
sec
0-59
msec
0-999 milliseconds
To set a single time for the entire buffer, it is usually adequate to set the time for
exp_num 0. (Conversely, this is the time that will be examined when a single
reading is desired for an entire sequence.) But, depending on the sequence and
timing parameters, successive exposures may be taken hours or even days later.
To set the exact exposure date and time for any successive exposure in the
sequence, specify a different exp_num. The exposure end time may be obtained
by adding the exposure duration that is obtained from pl_buf_get_exp_time
function.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_get_exp_date(4),pl_buf_get_exp_time(4),
pl_exp_start_seq(3)
NOTES
In most cases, the system will be unable to obtain a highly accurate value of the
time. (The milliseconds may be particularly inaccurate.) All inputs are checked
for proper ranges on input (using the ranges shown above). The inputs will
generate appropriate errors if they are out of range. Any value is allowed for the
year.
For most exposures, the start of exposure is easy to determine. (Time is
measured immediately before a call to pl_exp_start_seq.) In some cases
(such as triggered exposures), determining the start time may be more difficult.
Depending on the communication link to the camera, pl_exp_check_status
may be a few seconds out of date.
Chapter 7: Buffer Manipulation (Class 4)
109
PVCAM
Class 4: Buffer Manipulation
pl_buf_init(4)
NAME
pl_buf_init — initializes the buffer functions.
SYNOPSIS
rs_bool
pl_buf_init(void)
DESCRIPTION
This initializes the pointers and memory needed to use the buffer functions.
Since the buffer functions depend on internal tables, these tables must be
allocated and initialized before any buffer functions can be used. This function
should be called soon after pl_pvcam_init.
RETURN VALUE
TRUE for success. FALSE for a failure. Failure sets pl_error_code. If the
initialization fails, the buffer functions may not be used.
SEE ALSO
pl_buf_uninit(4),pl_pvcam_init(0)
NOTES
Currently, buffers are only needed if the exposure includes multiple regions or a
complex sequence. In that case, the function pl_exp_finish_seq will decode
a pixel stream and put the output onto the buffer.
For simple exposures, it may be easier and more efficient to examine the output
directly, by using the pixel_stream array that was passed into
pl_exp_start_seq. If this is done, the buffer routines will never be needed. It
will save space and time if the buffer routines are never referred to and never
initialized.
110
PVCAM Manual
Version 2.7
PVCAM
Class 4: Buffer Manipulation
pl_buf_uninit(4)
NAME
pl_buf_uninit — frees and releases the buffer functions.
SYNOPSIS
rs_bool
pl_buf_uninit(void)
DESCRIPTION
This frees and releases all pointers and memory allocated by the buffer
initialization. It should be called before calling pl_pvcam_uninit. Once the
buffers are uninitialized, buffer functions may not be used until the buffer library
has been reinitialized.
It is safe to call this function redundantly. If the buffer functions were never
initialized, or, if they have already been freed, this does no harm.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_buf_init(4), pl_pvcam_uninit(0)
NOTES
Chapter 8:
Code Examples
Example 1: pl_get_param & pl_get_enum_param
/*
/*
/*
/*
/*
This example displays information for currently defined parameter IDs.
Note: depending on the camera system connected the results will change
This example is broken into 3 functions main calls DisplayParamIdInfo
which calls DisplayEnumInfo to display enumerated data types and
DisplayIntsFltsInfo to display non-enum data types.
#include
#include
#include
#include
*/
*/
*/
*/
*/
"master.h"
"pvcam.h"
/* Prototype functions */
static void DisplayIntsFltsInfo (int16 hcam, uns32 param_id);
static void DisplayEnumInfo (int16 hcam, uns32 param_id);
static void DisplayParamIdInfo (int16 hcam, uns32 param_id);
int main(int argc, char **argv)
{
char cam_name[CAM_NAME_LEN];
int16 hCam;
/* camera name
*/
/* camera handle */
/* Initialize the PVCam Library and Open the First Camera */
pl_pvcam_init();
pl_cam_get_name( 0, cam_name );
pl_cam_open(cam_name, &hCam, OPEN_EXCLUSIVE );
printf( "\nAnti_Blooming\n");
DisplayParamIdInfo (hCam, PARAM_ANTI_BLOOMING);
printf( "\nLogic Output\n");
DisplayParamIdInfo (hCam, PARAM_LOGIC_OUTPUT);
printf( "\nEdge Trigger\n");
DisplayParamIdInfo (hCam, PARAM_EDGE_TRIGGER);
printf( "\nIntensifier Gain\n");
DisplayParamIdInfo (hCam, PARAM_INTENSIFIER_GAIN);
printf( "\nGate Mode\n");
DisplayParamIdInfo (hCam, PARAM_SHTR_GATE_MODE);
printf( "\nMin Block\n");
DisplayParamIdInfo (hCam, PARAM_MIN_BLOCK);
printf( "\nNum Min Block\n");
DisplayParamIdInfo (hCam, PARAM_NUM_MIN_BLOCK);
printf( "\nStrips Per Clean\n");
DisplayParamIdInfo (hCam, PARAM_NUM_OF_STRIPS_PER_CLR);
printf( "\nReadout Port\n");
DisplayParamIdInfo (hCam, PARAM_READOUT_PORT);
printf( "\nController Alive\n");
DisplayParamIdInfo (hCam, PARAM_CONTROLLER_ALIVE);
printf( "\nReadout Time\n");
DisplayParamIdInfo (hCam, PARAM_READOUT_TIME);
printf( "\nCircular Buffer Support\n");
DisplayParamIdInfo (hCam, PARAM_CIRC_BUFFER);
pl_cam_close( hCam );
pl_pvcam_uninit();
}
return 0;
/* This will display information we can get from parameter id */
void DisplayParamIdInfo (int16 hcam, uns32 param_id)
111
112
{
*/
PVCAM Manual
rs_bool status, status2;
rs_bool avail_flag;
uns16 access;
uns16 type;
/*
/*
/*
/*
status of pvcam functions
*/
ATTR_AVAIL, param is available
*/
ATTR_ACCESS, param is read, write or exists */
ATTR_TYPE, param data type
*/
status = pl_get_param(hcam, param_id, ATTR_AVAIL, (void *)&avail_flag);
/* check for errors */
if (status) {
/* check to see if parameter id is supported by hardware or software */
if (avail_flag) {
/* we got a valid parameter, now get access writes and data type
status = pl_get_param(hcam, param_id, ATTR_ACCESS, (void *)&access);
status2 = pl_get_param(hcam, param_id, ATTR_TYPE, (void *) &type);
if (status && status2) {
if (access == ACC_EXIST_CHECK_ONLY) {
printf(" param id %x exists\n", param_id);
}
else if ((access == ACC_READ_ONLY) ||
(access == ACC_READ_WRITE)) {
/* now we can start displaying information
*/
/* handle enumerated types separate from other data */
if (type == TYPE_ENUM) {
DisplayEnumInfo(hcam, param_id);
}
else {/* take care of the rest of the data types */
DisplayIntsFltsInfo(hcam, param_id);
}
}
else {
printf(" error in access check for param_id %x\n",
param_id);
}
}
else { /* error occurred calling function */
printf( "functions failed pl_get_param, with error code %ld\n",
pl_error_code());
}
}
else { /* parameter id is not available with current setup */
printf( " parameter %x is not available with current hardware"
" or software setup\n", param_id);
}
}
else { /* error occurred calling function print out error code */
printf( "functions failed pl_get_param, with error code %ld\n",
pl_error_code());
}
}
Version 2.7
printf( "Press Enter to Continue..." );
getchar();
fflush( stdin );
/* end of function DisplayParamIdInfo */
/* This routine assumes the param id is an enumerated type,
it will print out all the enumerated values that are allowed
with the param id and display the associated ASCII text. */
static void DisplayEnumInfo (int16 hcam, uns32 param_id)
{
rs_bool status;
/* status of pvcam functions
*/
uns32 count, index;
/* counters for enumerated types
*/
char enumStr[100];
/* string for enum text
*/
uns32 enumValue;
/* enum value returned for index & param id */
/* get number of enumerated values */
status = pl_get_param(hcam, param_id, ATTR_COUNT, (void *)&count);
if (status) {
printf(" enum values for param id %x\n", param_id);
for (index=0; index < count; index++) {
/* get enum value and enum string */
status = pl_get_enum_param(hcam, param_id, index, &enumValue,
enumStr, 100);
Chapter 8: Code Examples
/* if everything alright print out the results */
if (status) {
printf(" index =%ld enum value = %ld, text = %s\n",
index, enumValue, enumStr);
}
else {
printf( "functions failed pl_get_enum_param, "
"with error code %ld\n", pl_error_code());
}
}
}
}
else {
printf( "functions failed pl_get_param, with error code %ld\n",
pl_error_code());
}
/* end of function DisplayEnumInfo */
/* This routine displays all the information associated with the parameter id
given. This routine assumes that the data is either uns8, uns16, uns32,
int8, int16, int32, or flt64 */
static void DisplayIntsFltsInfo (int16 hcam, uns32 param_id)
{
/* current, min&max, & default values of parameter id */
union {
flt64 dval;
uns32 ulval;
int32 lval;
uns16 usval;
int16 sval;
uns8 ubval;
int8 bval;
} currentVal, minVal, maxVal, defaultVal, incrementVal;
uns16 type;
/* data type of parameter id */
rs_bool status, status2, status3,
status4, status5;
/* status of pvcam functions */
/* get the data type of parameter id */
status = pl_get_param(hcam, param_id, ATTR_TYPE, (void *)&type);
/* get the default, current, min and max values for parameter id */
/* Note : since the data type for these depends on the parameter */
/* id you have to call pl_get_param with the correct data type
*/
/* passed for param_value.
*/
if (status) {
switch (type) {
case TYPE_INT8:
status = pl_get_param(hcam, param_id, ATTR_CURRENT,
(void *)¤tVal.bval);
status2 = pl_get_param(hcam, param_id, ATTR_DEFAULT,
(void *)&defaultVal.bval);
status3 = pl_get_param(hcam, param_id, ATTR_MAX,
(void *)&maxVal.bval);
status4 = pl_get_param(hcam, param_id, ATTR_MIN,
(void *)&minVal.bval);
status5 = pl_get_param(hcam, param_id, ATTR_INCREMENT,
(void *)&incrementVal.bval);
printf(" param id %x\n", param_id);
printf(" current value = %c\n", currentVal.bval);
printf(" default value = %c\n", defaultVal.bval);
printf(" min = %c, max = %c\n", minVal.bval, maxVal.bval);
printf(" increment = %c\n", incrementVal.bval);
break;
case TYPE_UNS8:
status = pl_get_param(hcam, param_id, ATTR_CURRENT,
(void *)¤tVal.ubval);
status2 = pl_get_param(hcam, param_id, ATTR_DEFAULT,
(void *)&defaultVal.ubval);
status3 = pl_get_param(hcam, param_id, ATTR_MAX,
(void *)&maxVal.ubval);
status4 = pl_get_param(hcam, param_id, ATTR_MIN,
(void *)&minVal.ubval);
status5 = pl_get_param(hcam, param_id, ATTR_INCREMENT,
(void *)&incrementVal.ubval);
113
114
PVCAM Manual
Version 2.7
printf(" param id %x\n", param_id);
printf(" current value = %uc\n", currentVal.ubval);
printf(" default value = %uc\n", defaultVal.ubval);
printf(" min = %uc, max = %uc\n", minVal.ubval, maxVal.ubval);
printf(" increment = %uc\n", incrementVal.ubval);
break;
case TYPE_INT16:
status = pl_get_param(hcam, param_id, ATTR_CURRENT,
(void *)¤tVal.sval);
status2 = pl_get_param(hcam, param_id, ATTR_DEFAULT,
(void *)&defaultVal.sval);
status3 = pl_get_param(hcam, param_id, ATTR_MAX,
(void *)&maxVal.sval);
status4 = pl_get_param(hcam, param_id, ATTR_MIN,
(void *)&minVal.sval);
status5 = pl_get_param(hcam, param_id, ATTR_INCREMENT,
(void *)&incrementVal.sval);
printf(" param id %x\n", param_id);
printf(" current value = %i\n", currentVal.sval);
printf(" default value = %i\n", defaultVal.sval);
printf(" min = %i, max = %i\n", minVal.sval, maxVal.sval);
printf(" increment = %i\n", incrementVal.sval);
break;
case TYPE_UNS16:
status = pl_get_param(hcam, param_id, ATTR_CURRENT,
(void *)¤tVal.usval);
status2 = pl_get_param(hcam, param_id, ATTR_DEFAULT,
(void *)&defaultVal.usval);
status3 = pl_get_param(hcam, param_id, ATTR_MAX,
(void *)&maxVal.usval);
status4 = pl_get_param(hcam, param_id, ATTR_MIN,
(void *)&minVal.usval);
status5 = pl_get_param(hcam, param_id, ATTR_INCREMENT,
(void *)&incrementVal.usval);
printf(" param id %x\n", param_id);
printf(" current value = %u\n", currentVal.usval);
printf(" default value = %u\n", defaultVal.usval);
printf(" min = %uh, max = %u\n", minVal.usval, maxVal.usval);
printf(" increment = %u\n", incrementVal.usval);
break;
case TYPE_INT32:
status = pl_get_param(hcam, param_id, ATTR_CURRENT,
(void *)¤tVal.lval);
status2 = pl_get_param(hcam, param_id, ATTR_DEFAULT,
(void *)&defaultVal.lval);
status3 = pl_get_param(hcam, param_id, ATTR_MAX,
(void *)&maxVal.lval);
status4 = pl_get_param(hcam, param_id, ATTR_MIN,
(void *)&minVal.lval);
status5 = pl_get_param(hcam, param_id, ATTR_INCREMENT,
(void *)&incrementVal.lval);
printf(" param id %x\n", param_id);
printf(" current value = %ld\n", currentVal.lval);
printf(" default value = %ld\n", defaultVal.lval);
printf(" min = %ld, max = %ld\n", minVal.lval, maxVal.lval);
printf(" increment = %ld\n", incrementVal.lval);
break;
case TYPE_UNS32:
status = pl_get_param(hcam, param_id, ATTR_CURRENT,
(void *)¤tVal.ulval);
status2 = pl_get_param(hcam, param_id, ATTR_DEFAULT,
(void *)&defaultVal.ulval);
status3 = pl_get_param(hcam, param_id, ATTR_MAX,
(void *)&maxVal.ulval);
status4 = pl_get_param(hcam, param_id, ATTR_MIN,
(void *)&minVal.ulval);
status5 = pl_get_param(hcam, param_id, ATTR_INCREMENT,
(void *)&incrementVal.ulval);
printf(" param id %x\n", param_id);
printf(" current value = %ld\n", currentVal.ulval);
printf(" default value = %ld\n", defaultVal.ulval);
printf(" min = %ld, max = %ld\n", minVal.ulval, maxVal.ulval);
Chapter 8: Code Examples
115
printf(" increment = %ld\n", incrementVal.ulval);
break;
case TYPE_FLT64:
status = pl_get_param(hcam, param_id, ATTR_CURRENT,
(void *)¤tVal.dval);
status2 = pl_get_param(hcam, param_id, ATTR_DEFAULT,
(void *)&defaultVal.dval);
status3 = pl_get_param(hcam, param_id, ATTR_MAX,
(void *)&maxVal.dval);
status4 = pl_get_param(hcam, param_id, ATTR_MIN,
(void *)&minVal.dval);
status5 = pl_get_param(hcam, param_id, ATTR_INCREMENT,
(void *)&incrementVal.dval);
printf(" param id %x\n", param_id);
printf(" current value = %g\n", currentVal.dval);
printf(" default value = %g\n", defaultVal.dval);
printf(" min = %g, max = %g\n", minVal.dval, maxVal.dval);
printf(" increment = %g\n", incrementVal.dval);
break;
default:
printf(" data type not supported in this functions\n");
break;
}
if (!status || !status2 || !status3 || !status4 || !status5) {
printf( "functions failed pl_get_param, with error code %ld\n",
pl_error_code());
}
}
}
else {
printf( "functions failed pl_get_param, with error code %ld\n",
pl_error_code());
}
Example 2: pl_set_param
This example assumes data type to set is int16. This routine does do the error checks to make sure
you can write to the param and that its param id is an int16.
#include
#include
#include
#include
"master.h"
"pvcam.h"
/* Prototype functions */
static rs_bool SetParamExample (int16 hcam, uns32 param_id, int16 value);
int main(int argc, char **argv)
{
char cam_name[CAM_NAME_LEN];
int16 hCam;
/* camera name
*/
/* camera handle */
/* Initialize the PVCam Library and Open the First Camera */
pl_pvcam_init();
pl_cam_get_name( 0, cam_name );
pl_cam_open(cam_name, &hCam, OPEN_EXCLUSIVE );
/* Change the min skip block and number of min blocks to 2 and 100 */
SetParamExample(hCam, PARAM_MIN_BLOCK, 2);
SetParamExample(hCam, PARAM_NUM_MIN_BLOCK, 100);
pl_cam_close( hCam );
pl_pvcam_uninit();
}
return 0;
rs_bool SetParamExample (int16 hcam, uns32 param_id, int16 value)
116
{
PVCAM Manual
rs_bool status;
rs_bool avail_flag;
uns16 access;
uns16 type;
/*
/*
/*
/*
Version 2.7
status of pvcam functions
*/
ATTR_AVAIL, param is available
*/
ATTR_ACCESS, param is read, write or exists */
ATTR_TYPE, param data type
*/
status = pl_get_param(hcam, param_id, ATTR_AVAIL, (void *)&avail_flag);
/* check for errors */
if (status) {
/* check to see if parameter id is supported by hardware or software */
if (avail_flag) {
/* we got a valid parameter, now get access rights and data type */
status = pl_get_param(hcam, param_id, ATTR_ACCESS, (void *)&access);
if (status) {
if (access == ACC_EXIST_CHECK_ONLY) {
printf(" error param id %x is an exists check, "
"and not writable\n", param_id);
}
else if (access == ACC_READ_ONLY) {
printf(" error param id %x is a readonly variable, "
"and not writeable\n", param_id);
}
else if (access == ACC_READ_WRITE) {
/* we can set it, let's be safe and check to make sure
it is the right data type */
status = pl_get_param(hcam, param_id, ATTR_TYPE,
(void *) &type);
if (status) {
if (type == TYPE_INT16) {
/* OK lets write to it */
pl_set_param(hcam, param_id, (void *)&value);
printf( "param %x set to %i\n", param_id, value );
}
else {
printf( "data type mismatch for param_id "
"%x\n", param_id );
status = FALSE;
}
}
else {
printf( "functions failed pl_get_param, with "
"error code %ld\n", pl_error_code());
}
}
else {
printf(" error in access check for param_id "
"%x\n", param_id);
}
}
else { /* error occurred calling function */
printf( "functions failed pl_get_param, with error code %ld\n",
pl_error_code());
}
}
else { /* parameter id is not available with current setup */
printf(" parameter %x is not available with current hardware or "
"software setup\n", param_id);
}
}
else { /* error occurred calling function; print out error code */
printf( "functions failed pl_get_param, with error code %ld\n",
pl_error_code());
}
}
return(status);
Chapter 8: Code Examples
117
Example 3: Circular Buffer
Latest Frame Mode (FOCUS)
The following is an example of a circular buffer with the latest frame mode set. The example takes
the proper steps to set the camera up beforehand. (i.e., pl_cam_open, etc. and that pl_get_param
with parameter id PARAM_CIRC_BUFFER was used to verify that the system could perform circular
buffer operations) The following code will return the latest frame in the buffer.
#include
#include
#include
#include
"master.h"
"pvcam.h"
static void FocusContinuous( int16 hCam );
int main(int argc, char **argv)
{
char cam_name[CAM_NAME_LEN];
int16 hCam;
rs_bool avail_flag;
/* camera name
*/
/* camera handle
*/
/* ATTR_AVAIL, param is available */
/* Initialize the PVCam Library and Open the First Camera */
pl_pvcam_init();
pl_cam_get_name( 0, cam_name );
pl_cam_open(cam_name, &hCam, OPEN_EXCLUSIVE );
/* check for circular buffer support */
if( pl_get_param( hCam, PARAM_CIRC_BUFFER, ATTR_AVAIL, &avail_flag ) &&
avail_flag )
FocusContinuous( hCam );
else
printf( "circular buffers not supported\n" );
pl_cam_close( hCam );
pl_pvcam_uninit();
}
return 0;
void FocusContinuous( int16 hCam )
{
rgn_type region = { 0, 511, 1, 0, 511, 1 };
uns32 buffer_size, frame_size;
uns16 *buffer;
int16 status;
uns32 not_needed;
void_ptr address;
uns16 numberframes = 5;
/* Init a sequence set the region, exposure mode and exposure time */
pl_exp_init_seq();
pl_exp_setup_cont( hCam, 1, ®ion, TIMED_MODE, 100, &frame_size,
CIRC_OVERWRITE );
/* set up a circular buffer of 3 frames */
buffer_size = frame_size * 3;
buffer = (uns16*)malloc( buffer_size );
/* Start the acquisition */
printf( "Collecting %i Frames\n", numberframes );
pl_exp_start_cont(hCam, buffer, buffer_size );
/* ACQUISITION LOOP */
while( numberframes ) {
/* wait for data or error */
while( pl_exp_check_cont_status( hCam, &status, ¬_needed,
¬_needed ) &&
118
PVCAM Manual
(status != READOUT_COMPLETE && status != READOUT_FAILED) );
/* Check Error Codes */
if( status == READOUT_FAILED ) {
printf( "Data collection error: %i\n", pl_error_code() );
break;
}
if ( pl_exp_get_latest_frame( hCam, &address )) {
/* address now points to valid data */
printf( "Center Three Points: %i, %i, %i\n",
*((uns16*)address + frame_size/sizeof(uns16)/2 - 1),
*((uns16*)address + frame_size/sizeof(uns16)/2),
*((uns16*)address + frame_size/sizeof(uns16)/2 + 1) );
numberframes--;
printf( "Remaining Frames %i\n", numberframes );
}
} /* End while */
/* Stop the acquisition */
pl_exp_stop_cont(hCam,CCS_HALT);
/* Finish the sequence */
pl_exp_finish_seq( hCam, buffer, 0);
/*Uninit the sequence */
pl_exp_uninit_seq();
}
free( buffer );
Version 2.7
Chapter 8: Code Examples
119
Oldest Frame Mode (NFRAME)
The following is an example of a circular buffer with the oldest frame mode set. The example takes
the proper steps to set the camera up beforehand. (i.e., pl_cam_open, etc. and that pl_get_param
with parameter id PARAM_CIRC_BUFFER was used to verify that the system could perform circular
buffer operations) This code will return the frames in the order in which they arrived in the buffer,
without skipping a frame.
#include
#include
#include
#include
"master.h"
"pvcam.h"
static void AcquireContinuous( int16 hCam );
int main(int argc, char **argv)
{
char cam_name[CAM_NAME_LEN];
int16 hCam;
rs_bool avail_flag;
/* camera name
*/
/* camera handle
*/
/* ATTR_AVAIL, param is available */
/* Initialize the PVCam Library and Open the First Camera */
pl_pvcam_init();
pl_cam_get_name( 0, cam_name );
pl_cam_open(cam_name, &hCam, OPEN_EXCLUSIVE );
/* check for circular buffer support */
if( pl_get_param( hCam, PARAM_CIRC_BUFFER, ATTR_AVAIL, &avail_flag ) &&
avail_flag )
AcquireContinuous( hCam );
else
printf( "circular buffers not supported\n" );
pl_cam_close( hCam );
pl_pvcam_uninit();
}
return 0;
void AcquireContinuous( int16 hCam )
{
rgn_type region = { 0, 511, 1, 0, 511, 1 };
uns32 buffer_size, frame_size;
uns16 *buffer;
int16 status;
uns32 not_needed;
void_ptr address;
uns16 numberframes = 5;
/* Init a sequence set the region, exposure mode and exposure time */
pl_exp_init_seq();
pl_exp_setup_cont( hCam, 1, ®ion, TIMED_MODE, 100, &frame_size,
CIRC_NO_OVERWRITE );
/* set up a circular buffer of 3 frames */
buffer_size = frame_size * 3;
buffer = (uns16*)malloc( buffer_size );
/* Start the acquisition */
printf( "Collecting %i Frames\n", numberframes );
pl_exp_start_cont(hCam, buffer, buffer_size );
/* ACQUISITION LOOP */
while( numberframes ) {
/* wait for data or error */
while( pl_exp_check_cont_status( hCam, &status, ¬_needed,
¬_needed ) &&
(status != READOUT_COMPLETE && status != READOUT_FAILED) );
120
PVCAM Manual
/* Check Error Codes */
if( status == READOUT_FAILED ) {
printf( "Data collection error: %i\n", pl_error_code() );
break;
}
if ( pl_exp_get_oldest_frame( hCam, &address )) {
/* address now points to valid data */
printf( "Center Three Points: %i, %i, %i\n",
*((uns16*)address + frame_size/sizeof(uns16)/2 - 1),
*((uns16*)address + frame_size/sizeof(uns16)/2),
*((uns16*)address + frame_size/sizeof(uns16)/2 + 1) );
numberframes--;
printf( "Remaining Frames %i\n", numberframes );
pl_exp_unlock_oldest_frame( hCam );
}
} /* End while */
/* Stop the acquisition */
pl_exp_stop_cont(hCam,CCS_HALT);
/* Finish the sequence */
pl_exp_finish_seq( hCam, buffer, 0);
/*Uninit the sequence */
pl_exp_uninit_seq();
}
free( buffer );
Version 2.7
Chapter 8: Code Examples
121
Example 4: Standard Mode Acquisition
The following is a simple example of standard mode acquisitions from PVCAM with the minimum
set of functions for data acquisition. Note the example is hard-coded for a particular image size of
512 x 512; these normally should be variables.
#include
#include
#include
#include
"master.h"
"pvcam.h"
static void AcquireStandard( int16 hCam );
int main(int argc, char **argv)
{
char cam_name[CAM_NAME_LEN];
int16 hCam;
/* camera name
/* camera handle
*/
*/
/* Initialize the PVCam Library and Open the First Camera */
pl_pvcam_init();
pl_cam_get_name( 0, cam_name );
pl_cam_open(cam_name, &hCam, OPEN_EXCLUSIVE );
AcquireStandard( hCam );
pl_cam_close( hCam );
pl_pvcam_uninit();
}
return 0;
void AcquireStandard( int16 hCam )
{
rgn_type region = { 0, 511, 1, 0, 511, 1 };
uns32 size;
uns16 *frame;
int16 status;
uns32 not_needed;
uns16 numberframes = 5;
/* Init a sequence set the region, exposure mode and exposure time */
pl_exp_init_seq();
pl_exp_setup_seq( hCam, 1, 1, ®ion, TIMED_MODE, 100, &size );
frame = (uns16*)malloc( size );
/* Start the acquisition */
printf( "Collecting %i Frames\n", numberframes );
/* ACQUISITION LOOP */
while( numberframes ) {
pl_exp_start_seq(hCam, frame );
/* wait for data or error */
while( pl_exp_check_status( hCam, &status, ¬_needed ) &&
(status != READOUT_COMPLETE && status != READOUT_FAILED) );
/* Check Error Codes */
if( status == READOUT_FAILED ) {
printf( "Data collection error: %i\n", pl_error_code() );
break;
}
/* frame now contains valid data */
printf( "Center Three Points: %i, %i, %i\n",
frame[size/sizeof(uns16)/2 - 1],
frame[size/sizeof(uns16)/2],
frame[size/sizeof(uns16)/2 + 1] );
122
PVCAM Manual
numberframes--;
printf( "Remaining Frames %i\n", numberframes );
} /* End while */
/* Finish the sequence */
pl_exp_finish_seq( hCam, frame, 0);
/*Uninit the sequence */
pl_exp_uninit_seq();
}
free( frame );
Version 2.7
Appendix A:
Error Codes
All successful functions reset pl_error_code to 0, which produces the message "no error".
All unsuccessful functions return a numeric value, where that value corresponds to a number linked
to an error message. All of the PVCAM error numbers and their linked error messages are listed in
the table that follows. This table will be updated as new error messages are added.
Table 5. Error Codes
Error #
Error Message
Meaning
0
PVCAM_SUCCESS
No error
1
C0_UNKNOWN_ERROR
Unexpected, unanticipated, or undocumented
2
DDI_NOT_PV_DEVICE
This device driver is not a Roper device
3
DDI_BAD_DEV_NAME
No driver found with the specified name
4
DDI_DRIVER_IN_USE
This driver is already in use by another user
5
DDI_ALREADY_OPEN
This driver has already been opened
6
DDI_CANT_OPEN_DRIVER
The driver was found, but could not be opened
7
DDI_CANT_CLOSE_DRIVER
Driver is not currently open; it can't be closed
8
DDI_CLOSE_ERROR
An error occurred while trying to close the driver
9
DDI_ALREADY_ACTIVE
Camera is already taking data; finish or abort
10
DDI_ZERO_SEND_SIZE
Invalid request: transmit zero bytes
11
DDI_ZERO_RECV_SIZE
Invalid request: receive zero bytes
12
DDI_IOPORT_CONFLICT
2 cameras are using the same I/O port
13
DDI_BOARD_NOT_FOUND
Communications board is not at expected location
14
DDI_CABLE_DISCONNECTED
Camera electronics unit cable is not connected
15
DDI_MEM_ALLOC_FAILED
Device driver could not allocate needed memory
16
DDI_IRQID_CONFLICT
2 open cameras are using the same interrupt ID
17
DDI_DRV_CLOS_CLOSE_CAM
Driver not yet opened: pd_cam_close
18
DDI_DRV_CLOS_READ_BYTE
Driver not yet opened: pd_cam_write_read, read
19
DDI_DRV_CLOS_SEND_BYTE
Driver not yet opened: pd_cam_write_read, write
20
DDI_DRV_CLOS_GET_RETRY
Driver not yet opened: pd_driver_get_retries
21
DDI_DRV_CLOS_SET_RETRY
Driver not yet opened: pd_driver_set_retries
22
DDI_DRV_CLOS_GET_TIME
Driver not yet opened: pd_driver_get_timeout
23
DDI_DRV_CLOS_SET_TIME
Driver not yet opened: pd_driver_set_timeout
24
DDI_DRV_CLOS_INFO_LEN
Driver not yet opened: pd_driver_get_info_length
25
DDI_DRV_CLOS_INFO_DUMP
Driver not yet opened: pd_driver_get_info_dump
123
124
Error #
PVCAM Manual
Error Message
Version 2.7
Meaning
26
DDI_DRV_CLOS_DRV_VER
Driver not yet opened: pd_driver_get_ver
27
DDI_DRV_CLOS_IM_STATUS
Driver not open: pd_driver_get_image_data_status
28
DDI_DRV_CLOS_IM_ABORT
Driver not open: pd_driver_set_image_data_idle
29
DDI_DRV_CLOS_IM_ACTIVE
Driver not open: pd_driver_set_image_data_active
30
DDI_DRV_CLOS_IM_GRAN
Driver not open: pd_driver_get_image_data_gran
31
DDI_BAD_DEVH_CLOSE_CAM
Illegal device handle: pd_cam_close
32
DDI_BAD_DEVH_READ_BYTE
Illegal device handle: pd_cam_write_read, read
33
DDI_BAD_DEVH_SEND_BYTE
Illegal device handle: pd_cam_write_read, write
34
DDI_BAD_DEVH_GET_RETRY
Illegal device handle: pd_driver_get_retries
35
DDI_BAD_DEVH_SET_RETRY
Illegal device handle: pd_driver_set_retries
36
DDI_BAD_DEVH_GET_TIME
Illegal device handle: pd_driver_get_timeout
37
DDI_BAD_DEVH_SET_TIME
Illegal device handle: pd_driver_set_timeout
38
DDI_BAD_DEVH_INFO_LEN
Illegal device handle: pd_driver_get_info_length
39
DDI_BAD_DEVH_INFO_DUMP
Illegal device handle: pd_driver_get_info_dump
40
DDI_BAD_DEVH_DRV_VER
Illegal device handle: pd_driver_get_ver
41
DDI_BAD_DEVH_IM_STATUS
Bad dev handle: pd_driver_get_image_data_status
42
DDI_BAD_DEVH_IM_ABORT
Bad dev handle: pd_driver_set_image_data_idle
43
DDI_BAD_DEVH_IM_ACTIVE
Bad dev handle: pd_driver_set_image_data_active
44
DDI_BAD_DEVH_IM_GRAN
Bad dev handle: pd_driver_get_image_data_gran
45
DDI_SYS_ERR_DEV_DRIVER
System error while accessing the device driver
46
DDI_SYS_ERR_INIT
System error in pd_ddi_init
47
DDI_SYS_ERR_UNINIT
System error in pd_ddi_uninit
48
DDI_SYS_ERR_TOTL_CAMS
System error in pd_ddi_get_total_cams
49
DDI_SYS_ERR_CAM_NAME
System error in pd_ddi_get_all_cam_names
50
DDI_SYS_ERR_OPEN_CAM
System error in pd_cam_open
51
DDI_SYS_ERR_CLOSE_CAM
System error in pd_cam_close
52
DDI_SYS_ERR_READ_BYTE
System error in pd_cam_write_read, read
53
DDI_SYS_ERR_SEND_BYTE
System error in pd_cam_write_read, write
54
DDI_SYS_ERR_GET_RETRY
System error in pd_driver_get_retries
55
DDI_SYS_ERR_SET_RETRY
System error in pd_driver_set_retries
56
DDI_SYS_ERR_GET_TIME
System error in pd_driver_get_timeout
57
DDI_SYS_ERR_SET_TIME
System error in pd_driver_set_timeout
58
DDI_SYS_ERR_INFO_LEN
System error in pd_driver_get_info_length
59
DDI_SYS_ERR_INFO_DUMP
System error in pd_driver_get_info_dump
60
DDI_SYS_ERR_DRV_VER
System error in pd_driver_get_ver
Appendix A: Error Codes
Error #
Error Message
125
Meaning
61
DDI_SYS_ERR_IM_STATUS
System error in pd_driver_get_image_data_status
62
DDI_SYS_ERR_IM_ABORT
System error in pd_driver_set_image_data_idle
63
DDI_SYS_ERR_IM_ACTIVE
System error in pd_driver_set_image_data_active
64
DDI_SYS_ERR_IM_GRAN
System error in pd_driver_get_image_data_gran
65
DDI_UNKNOWN_DEV_DRIVER
Unknown error while accessing the device driver
66
DDI_UNKNOWN_INIT
Unknown error in pd_ddi_init
67
DDI_UNKNOWN_UNINIT
Unknown error in pd_ddi_uninit
68
DDI_UNKNOWN_TOTL_CAMS
Unknown error in pd_ddi_get_total_cams
69
DDI_UNKNOWN_CAM_NAME
Unknown error in pd_ddi_get_all_cam_names
70
DDI_UNKNOWN_OPEN_CAM
Unknown error in pd_cam_open
71
DDI_UNKNOWN_CLOSE_CAM
Unknown error in pd_cam_close
72
DDI_UNKNOWN_READ_BYTE
Unknown error in pd_cam_write_read, read
73
DDI_UNKNOWN_SEND_BYTE
Unknown error in pd_cam_write_read,write
74
DDI_UNKNOWN_GET_RETRY
Unknown error in pd_driver_get_retries
75
DDI_UNKNOWN_SET_RETRY
Unknown error in pd_driver_set_retries
76
DDI_UNKNOWN_GET_TIME
Unknown error in pd_driver_get_timeout
77
DDI_UNKNOWN_SET_TIME
Unknown error in pd_driver_set_timeout
78
DDI_UNKNOWN_INFO_LEN
Unknown error in pd_driver_get_info_length
79
DDI_UNKNOWN_INFO_DUMP
Unknown error in pd_driver_get_info_dump
80
DDI_UNKNOWN_DRV_VER
Unknown error in pd_driver_get_ver
81
DDI_UNKNOWN_IM_STATUS
Unknown error in pd_driver_get_image_data_status
82
DDI_UNKNOWN_IM_ABORT
Unknown error in pd_driver_set_image_data_idle
83
DDI_UNKNOWN_IM_ACTIVE
Unknown error in pd_driver_set_image_data_active
84
DDI_UNKNOWN_IM_GRAN
Unknown error in pd_driver_get_image_data_gran
85
DDI_SCSI_NOT_PV_CAMERA
This SCSI device is not a Tucson camera
86
DDI_SCSI_NO_PROTOCOL
SCSI protocol breakdown: no device or termination
87
DDI_SCSI_NO_ARBITRATE
SCSI arbitration failure: the bus is busy
88
DDI_SCSI_BAD_XFER
SCSI bad instruction in transfer instruction bloc
89
DDI_SCSI_PHASE_ERROR
SCSI phase error: host & camera disagree on type
90
DDI_SCSI_DATA_ERROR
SCSI data comparison error verifying transfer
91
DDI_SCSI_MGR_BUSY
SCSI manager is busy with another operation
92
DDI_SCSI_SEQUENCE_ERR
SCSI sequencing error
93
DDI_SCSI_BUS_TIMEOUT
SCSI bus timeout waiting for data transfer
94
DDI_SCSI_COMPLETE_ERR
SCSI completion error
95
DDI_SCSI_INTERNAL_ERR
SCSI device indicates an internal error
126
Error #
PVCAM Manual
Error Message
Version 2.7
Meaning
96
DDI_XM_SNDOK
XMODEM
97
DDI_XM_NOSOH
XMODEM
98
DDI_XM_OVERFLOW
XMODEM
99
DDI_XM_RCVOK
XMODEM
100
DDI_XM_RCVCAN
XMODEM
101
DDI_XM_NOACK
XMODEM no ACKnowledge signal received
102
DDI_XM_LASTACK
XMODEM
103
DDI_XM_SNDACK
XMODEM
104
DDI_XM_SNDCAN
XMODEM
105
DDI_XM_MSGEND
XMODEM
106
DDI_XM_BADCKV
XMODEM
107
DDI_XM_BADSOH
XMODEM
108
DDI_XM_NODATA
XMODEM
109
DDI_XM_BADPAK
XMODEM
110
DDI_XM_PAKNUM
XMODEM
111
DDI_XM_PAKSEQ
XMODEM
112
DDI_XM_NOSYNC
XMODEM no SYNC character seen
113
DDI_XM_SYNCTOUT
XMODEM timout while waiting for SYNC
character
114
DDI_XM_XMITLOCK
XMODEM transmit ... ?
115
DDI_XM_BADCMD
XMODEM bad command
116
C0_INVALID_HANDLE
This is not the handle of an open camera
117
C0_CAM_ALREADY_OPEN
This user has already opened this camera
118
C0_CAM_NEVER_OPENED
Camera was not opened, so this task can't be done
119
C0_CAM_RESERVED
The camera is in use by another user
120
C0_DRIVER_OUT_OF_MEM
Driver or DDI ran out of (specialized?) memory
121
C0_CANT_READ_TIMEOUT
System couldn't read the timeout for this driver
122
C0_CANT_WRIT_TIMEOUT
System couldn't set the timeout for this driver
123
C0_CANT_READ_RETRIES
System couldn't read the retries for this driver
124
C0_CANT_WRIT_RETRIES
System couldn't set the retries for this driver
125
C0_CAM_TIMEOUT
No response at all from the camera
126
C0_CAM_TIMEOUT_NOISE
Timeout, but some response (noisy line?)
127
C0_RETRIES_EXCEEDED
Not a timeout, but retries didn't work (noisy?)
128
C0_CAM_NAME_OUT_OF_RNG
The number must be in the range
1<=num<=totl_cams
129
C0_CAM_NAME_NOT_FOUND
This is not a valid name for opening the camera
Appendix A: Error Codes
Error #
Error Message
127
Meaning
130
C0_PACKET_TOO_LARGE
A send or read request used a packet >32768 bytes
131
C0_STATUS_TOO_LARGE
The status info returned contained too many bytes
132
C0_STATUS_TOO_SMALL
The status info returned contained too few bytes
133
C0_NEED_POSITIVE_VAL
The input value must be greater than zero
134
C0_NEED_ZERO_OR_MORE
The input value must be zero or above
135
C0_NULL_POINTER
Input pointer is null, it must be a legal address
136
C0_STSF_EU_CPU
Subsystem fault: electronics unit main CPU
137
C0_STSF_EU_SYS_INTEG
Subsystem fault: EU internal communications
138
C0_STSF_EU_TO_HOST
Subsystem fault: EU-to-host cables
139
C0_STSF_POWER_SUPPLY
Subsystem fault: power supply voltage error
140
C0_STSF_CCS_CHIP
Subsystem fault: CCS chip or memory
141
C0_STSF_CCS_SCRIPT_MEM
Subsystem fault: CCS script memory
142
C0_STSF_CCS_PORTS
Subsystem fault: CCS ports
143
C0_STSF_DISPLAY
Subsystem fault: EU front panel display
144
C0_STSF_SHUTTER_DRIVE
Subsystem fault: shutter driver circuit
145
C0_STSF_TEMP_CONT
Subsystem fault: temperature control circuit
146
C0_STSF_PAR_CLOCK_DRV
Subsystem fault: parallel clock driver
147
C0_STSF_CH_CABLES
Subsystem fault: camera head cables
148
C0_STSF_CH_CPU
Subsystem fault: camera head CPU board
149
C0_STSF_CH_CLOCK_BRD
Subsystem fault: camera head clock board
150
C0_STSF_CH_POWER_BRD
Subsystem fault: camera head power board
151
C0_STSF_CH_VID_BRD_1
Subsystem fault: camera head video board #1
152
C0_STSF_CH_VID_BRD_2
Subsystem fault: camera head video board #2
153
C0_STSF_CH_VID_BRD_3
Subsystem fault: camera head video board #3
154
C0_STSF_CH_VID_BRD_4
Subsystem fault: camera head video board #4
155
C0_STSF_ADC_BOARD_1
Subsystem fault: A/D board #1
156
C0_STSF_ADC_BOARD_2
Subsystem fault: A/D board #2
157
C0_STSF_ADC_BOARD_3
Subsystem fault: A/D board #3
158
C0_STSF_ADC_BOARD_4
Subsystem fault: A/D board #4
159
C0_STSF_OPTION_CARD_1
Subsystem fault: option card #1
160
C0_STSF_OPTION_CARD_2
Subsystem fault: option card #2
161
C0_STSF_OPTION_CARD_3
Subsystem fault: option card #3
162
C0_STSF_OPTION_CARD_4
Subsystem fault: option card #4
163
C0_NO_IMG_DATA
Can't collect data: expected data is zero bytes
164
C0_CCL_SCRIPT_INVALID
Can't collect data: CCS script is invalid
128
Error #
PVCAM Manual
Error Message
Version 2.7
Meaning
165
C0_EXP_FIFO_OVERFLOW
AIA input buffer has overflowed
166
C0_EXP_NO_ACK
Camera didn't acknowledge request for image data
167
C0_EXP_XFER_ERR
Last data transfer from the camera was garbled
168
C0_EXP_EXTRA_DATA
Finished data transfer, but extra data exists
169
C0_EXP_MISSING_DATA
Finished data transfer, some data was missing
170
C0_OPEN_MODE_UNAVAIL
Camera may not be opened in the mode specified
171
C0_WRONG_READ_CLASS
Read operations require the HOST_COMMANDS
class
172
C0_WRITE_BYTES_TOO_SML
Command sent to camera must be at least 1 byte
173
C0_WRITE_BYTES_TOO_LRG
Cannot send over 32768 bytes in one transaction
174
C0_READ_BYTES_TOO_SML
A read transaction must transfer at least 1 byte
175
C0_READ_BYTES_TOO_LRG
Cannot read over 32768 bytes in one transaction
176
C0_WRONG_READ_CMD
'read' command is improperly formatted
177
DDI_DRV_CLOS_GET_PIXTIME
Driver not yet opened: pd_driver_get_pixtime
178
DDI_SYS_ERR_GET_PIXTIME
System error in pd_driver_get_pixtime
179
DDI_BAD_DEVH_GET_PIXTIME
Bad dev handle: pd_driver_get_pixtime
180
DDI_UNKNOWN_GET_PIXTIME
Unknown error in pd_driver_get_pixtime
181
DDI_CAM_XOFF
Camera can't communicate after sending an X-OFF
182
C0_BAD_CONTROLLER
Controller for camera not valid
183
C0_CNTRL_CREATE_FAILED
Could not create controller object for camera
184
C0_NO_CONT_STATUS
Status not available for continuous exposure
185
C0_STAT_CNTRL_ERROR
Controller error while requesting status
186
C0_STAT_CMD_ERROR
Command error while requesting status
187
C0_STAT_DMA_OVERRUN
DMA data overrun has occurred
188
C0_STAT_TAXI_VIOLATION
Violation in TAXI communication protocol occurred
189
C0_STAT_MAILBOX_ERROR
Mailbox error while requesting status
190
C0_STAT_CH0_ERROR
Channel 0 transfer not enabled
191
C0_STAT_CH1_ERROR
Channel 1 transfer not enabled
192
C0_CANT_READ_ID
System couldn't read the subsystem part numbers
193
C0_CANT_READ_NAME
System couldn't read the name for this subsystem
194
C0_DEV_HANDLE_UNAVAIL
Camera device handle unavailable
195
C0_PVCAM_NOT_INITED
Camera library not initialized
196
C0_NOT_INITIALIZED
The pg_decode_info structure is not initialized
1000
C01_START_ERROR
unknown error
2000
C2_UNKNOWN_ERROR
Unexpected, unanticipated, undocumented
Appendix A: Error Codes
Error #
Error Message
129
Meaning
2001
C2_PVCAM_ALREADY_INITED
Init_pvcam has been called twice without closing
2002
C2_PVCAM_NOT_INITED
The PVCAM library was never initialized
2003
C2_FAILED_TO_SET_VALUE
The camera did not accept the new setting
2004
C2_NEED_POSITIVE_VAL
The input value must be greater than zero
2005
C2_NEED_ZERO_OR_MORE
The input value must be zero or above
2006
C2_NULL_POINTER
Input pointer is null, it must be a legal address
2007
C2_FRAME_XFER_ILLEGAL
This CCD does not allow frame transfer operation
2008
C2_FRAME_XFER_REQUIRED
This CCD must be operated in frame transfer mode
2009
C2_MPP_MODE_ILLEGAL
This CCD does not allow mpp-mode clocking
2010
C2_MPP_MODE_REQUIRED
This CCD requires mpp-mode clocking
2011
C2_CLEAR_MODE_INVALID
Requested clear mode is not an allowed choice
2012
C2_SPEED_INVALID
No valid speeds between camera/electronics/host
2013
C2_SPEED_OUT_OF_RANGE
Selected a non-existant speed table entry
2014
C2_CANT_SET_ADC_OFFSET
Camera does not allow offset to be read or set
2015
C2_BAD_CONTROLLER
Controller for camera not valid
2016
C2_NOT_AVAILABLE
Parameter is not available for camera
2017
C2_FAILED_TO_GET_VALUE
The camera did not return the setting
2018
C2_PARAMETER_INVALID
The requested parameter is invalid
2019
C2_ATTRIBUTE_INVALID
The requested attribute is invalid
2020
C2_INDEX_OUT_OF_RANGE
The requested parameter index is out of range
2021
C2_NOT_INPUT
The requested I/O port is not an input port
2022
C2_IO_TYPE_INVALID
The requested I/O port type is not supported
2023
C2_ADDR_OUT_OF_RANGE
The I/O address is out of range
2024
C2_ACCESS_ATTR_INVALID
The I/O port returned access attribute is invalid
2025
C2_CANT_SET_PARAMETER
The requested parameter cannot be set
2026
C2_IO_DIRECTION_INVALID
The returned direction for the I/O port is invalid
2027
C2_NO_ALPHA_SER_NUM
Alphanumeric serial # unavailable for this camera
2028
C2_CANT_OVERSCAN
Camera does not allow overscanning the CCD
2029
C2_CANT_SET_GAIN_MULT
Camera does not allow setting the gain multiplier
3000
C3_INVALID_PIC_TRIGGER_MODE
Invalid PIC trigger mode
3001
C3_NO_COMMUNICATIONS_LINK
Bogus temp
3002
C3_INVALID_SCRIPT
CCL program is not loaded or is invalid
3003
C3_EXP_EXTRA_DATA
Extra data acquired during exposure
3004
C3_EXP_NO_DATA_ACQ
No data acquired during exposure
3005
C3_EXP_FIFO_OVERFLOW
FIFO overflow during exposure
130
Error #
PVCAM Manual
Error Message
Version 2.7
Meaning
3006
C3_EXP_NO_ACKNOWLEDGE
Camera did not acknowledge request during exp
3007
C3_EXP_TRANSFER_ERROR
Transfer error during exposure
3008
C3_EXP_UNKNOWN_STATE
Camera went into unknown state during exp
3009
C3_CANT_DECODE_IN_PROGRESS
Can't decode while readout is in progress
3010
C3_RGN_MAX_EXCEEDED
Trying to exceed the maximum # of regions
3011
C3_RGN_ILLEGAL_DEFN
Dimensions of region to be added is illegal
3012
C3_RGN_ILLEGAL_BINNING
Binning of region to be added is illegal
3013
C3_RGN_OUTSIDE_CCD_DIMENS
Region def extends beyond CCD dimensions
3014
C3_RGN_OVERLAP
Region to be added overlaps a previous region
3015
C3_RGN_INVALID_NUM
Invalid region number
3016
C3_RGN_NOT_FOUND
Region not found
3017
C3_STREAM_PTR_NOT_DEFINED
Pointer to pixel stream is not defined
3018
C3_GROUPS_PTR_NOT_DEFINED
Pointer to decode info structure undefined
3019
C3_NOT_INITIALIZED
pl_init_exp_seq() has not been called
3020
C3_FAILED_TO_SET_VALUE
The value can not be set in the camera
3021
C3_EVENT_NUMBER_INVALID
Frame count for generating event <= 0
3022
C3_EVENT_NOT_SUPPORTED
Specified event is not supported by the O.S.
3023
C3_BAD_CONTROLLER
Controller for camera not valid
3024
C3_EVENT_NOT_SET
Event was not set up
3025
C3_CNTRL_INIT_FAILED
Controller initialization failed
3026
C3_EXP_MODE_NOT_SUPPORTED
Exposure mode not supported by this camera
3027
C3_ILLEGAL_BUFFER_SIZE
Buffer must be integer-multiple of frame size
3028
C3_GET_FRAME_NOT_SUPPORTED
Camera cannot return the specified frame
3029
C3_FRAME_NOT_RETURNED
Specified frame could not be returned
3030
C3_FRAME_BAD_MODE
Frame could not be returned in current mode
3031
C3_NO_DRIVER_BUFFER
Camera does not provide a driver buffer
3032
C3_BUF_NOT_RETURNED
Pointer to buffer could not be returned
3033
C3_BUFFER_OVERRUN
Data Buffer is full no place to xfer data
3034
C3_TAXI_VIOLATION
Communication with device failed, link broken
3035
C3_EXP_RES_OUT_OF_RANGE
Exposure resolution index non-existent
3036
C3_NOT_AVAILABLE
Parameter is not available for camera
3037
C3_IO_PORT_INVALID
Specified I/O port is invalid
3038
C3_FAILED_TO_GET_VALUE
The camera did not return the setting
3039
C3_IO_STATE_OUT_OF_RANGE
Requested I/O state out of range for port
3040
C3_IO_LOCATION_INVALID
Specified script location is invalid
Appendix A: Error Codes
Error #
Error Message
131
Meaning
3041
C3_IO_NOT_OUTPUT
Specified I/O port is not an output port
3042
C3_EXP_XFER_ERR
Last data transfer from the camera was garbled
3043
C3_EXP_MISSING_DATA
Finished data transfer, some data was missing
3044
C3_STAT_CNTRL_ERROR
Controller error while requesting status
3045
C3_STAT_CMD_ERROR
Command error while requesting status
3046
C3_CAM_NEVER_OPENED
Camera was not opened, so this task can't be done
3047
C3_STAT_DMA_OVERRUN
DMA data overrun has occurred
3048
C3_STAT_TAXI_VIOLATION
Violation in TAXI communication protocol occurred
3049
C3_STAT_MAILBOX_ERROR
Mailbox error while requesting status
3050
C3_STAT_CH0_ERROR
Channel 0 transfer not enabled
3051
C3_STAT_CH1_ERROR
Channel 1 transfer not enabled
3052
C3_UNKNOWN_ERROR
Unexpected, unanticipated, undocumented
4000
C04_HBUF_OUTOFRANGE
HBUF is out of range
4001
C04_HIMG_OUTOFRANGE
HIMG is out of range
4002
C04_NO_FREE_BUFFER_HANDLES
No free buffer handles available
4003
C04_NO_FREE_IMAGE_HANDLES
No free image handles available
4004
C04_BUFFER_ENTRY_ALREADY_SET
Buffer entry is already set
4005
C04_BUFFER_ENTRY_ALREADY
_CLEARED
Buffer entry is already cleared
4006
C04_IMAGE_ENTRY_ALREADY_SET
Image entry is already set
4007
C04_IMAGE_ENTRY_ALREADY
_CLEARED
Image entry is already cleared
4008
C04_INVALID_IMAGE_HANDLE
Invalid image handle
4009
C04_INVALID_BUFFER_HANDLE
Invalid buffer handle
4010
C04_INVALID_BITDEPTH_VALUE
Bit depth must be enum PRECISION_...
4011
C04_INVALID_IMAGE_NUMBER
Invalid image number
4012
C04_INVALID_EXPOSURE_NUMBER
Invalid exposure number
4013
C04_INVALID_TIME
The time or date is out of range
4014
C04_INVALID_REGION
A region is out of range
14000
C14_UNKNOWN_ERROR
Unexpected, unanticipated, undocumented
14001
C14_CANT_READ_INI_FILE
Unable to read the current INI file. Please run
RSConfig.exe
29000
C29_UNKNOWN_ERROR
Unexpected, unanticipated, undocumented
29001
C29_BDEPTH_ILLEGAL
Bit depth must be enum PRECISION_...
29002
C29_BDEPTH_DIFFER
Bit depth source much match destination
29003
C29_BUF_NEEDS_1_EXP
A buffer needs at least 1 exposure
132
PVCAM Manual
Error #
Error Message
Version 2.7
Meaning
29004
C29_BUF_NEEDS_1_IMG
A buffer needs at least 1 image
29005
C29_IMG_DEF_TOO_LARGE
Image definition used too large a value
29006
C29_IMG_DEF_TOO_SMALL
Image size/bin must be larger than zero
29007
C29_IMG_DEF_DIFFER
Image source definition must match dest
29008
C29_IMG_NUM_DIFFER
Source # of images must match dest
30000
C30_UNKNOWN_ERROR
Unexpected, unanticipated, undocumented
30001
C30_CANT_READ_TIME
Unable to read the current system time
30002
C30_END
31000
C31_INVALID_HEAP
Invalid heap ID: PUBLIC_MEM, PRIVATE_MEM
31001
C31_MEMALLOC_FAILED
Not enough memory to perform alloc
31002
C31_MEMCALLOC_FAILED
Not enough memory to perform calloc
31003
C31_MEMREALLOC_FAILED
Not enough memory to perform realloc
31004
C31_PRIV_MEM_BLOCK_TOO_BIG
Excceeds 64k limit for PRIVATE_MEM
31005
C31_MEMLOCK_FAILED
Memory page locking failed
32000
CCL_TOO_COMPLEX
Too many script entries
32001
CCL_CANT_FRAME_TRANSFER
No frame transfer hardware support
32002
CCL_SCRIPT_IS_NOT_VALID
Invalid script
32003
CCL_REGIONS_OVERLAP
Regions contain some of the same pixels
32004
CCL_INVALID_SERIAL_BINNING
Serial binning == 0 or > region size
32005
CCL_INVALID_PARALLEL_BINNING
Parallel binning == 0 or > region size
32006
CCL_NONMATCHED_PARALLEL
_BINNING
Conflicting parallel binning values
32007
CCL_PARALLEL_BINNING_MISALIGNED
Conflicting parallel binning alignment
32008
CCL_INVALID_REGION
Region is not on the CCD
32009
CCL_INVALID_IO_PORT_TYPE
Requested I/O port is not a valid type
32010
C32_NOT_INITIALIZED
The pg_decode_info structure is not initialized
Appendix B:
Obsolete Functions
The following list of functions have been made obsolete through the use of pl_get_param,
pl_set_param, pl_get_enum_param, and pl_enum_str_length functions. They still
function correctly and are still supported, but for future programming, the following functions
should not be used. For more information about the pl_get_param and pl_set_param
parameter ids, refer to Chapter 5.
Table 6. Obsolete Class 0 Functions and Their pl_set_param/pl_set_param Equivalents
Obsolete Class 0 Function
pl_set_param/pl_get_param Equivalent
pl_dd_get_info
PARAM_DD_INFO
pl_dd_get_info_length
PARAM_DD_INFO_LENGTH
pl_dd_get_retries
PARAM_DD_RETRIES
pl_dd_set_retries
PARAM_DD_RETRIES
pl_dd_get_timeout
PARAM_DD_TIMEOUT
pl_dd_set_timeout
PARAM_DD_TIMEOUT
pl_dd_get_ver
PARAM_DD_VERSION
Table 7. Obsolete Class 2 Functions and Their pl_set_param/pl_set_param Equivalents
Obsolete Class 2 Function
pl_set_param/pl_get_param Equivalent
pl_ccd_get_adc_offset
PARAM_ADC_OFFSET
pl_ccd_get_chip_name
PARAM_CHIP_NAME
pl_ccd_get_clear_cycles
PARAM_CLEAR_CYCLES
pl_ccd_get_clear_mode
PARAM_CLEAR_MODE
pl_ccd_get_color_mode
PARAM_COLOR_MODE
pl_ccd_get_cooling_mode
PARAM_COOLING_MODE
pl_ccd_get_frame_capable
PARAM_FRAME_CAPABLE
pl_ccd_get_fwell_capacity
PARAM_FWELL_CAPACITY
pl_ccd_get_mpp_capable
PARAM_MPP_CAPABLE
pl_ccd_get_par_size
PARAM_PAR_SIZE
pl_ccd_get_pix_par_dist
PARAM_PIX_PAR_DIST
pl_ccd_get_pix_par_size
PARAM_PIX_PAR_SIZE
pl_ccd_get_pix_ser_dist
PARAM_PIX_SER_DIST
pl_ccd_get_pix_ser_size
PARAM_PIX_SER_SIZE
133
134
PVCAM Manual
Obsolete Class 2 Function
Version 2.7
pl_set_param/pl_get_param Equivalent
pl_ccd_get_pmode
PARAM_PMODE
pl_ccd_get_postmask
PARAM_POSTMASK
pl_ccd_get_postscan
PARAM_POSTSCAN
pl_ccd_get_preamp_dly
PARAM_PREAMP_DELAY
pl_ccd_get_preamp_off_control
PARAM_PREAMP_OFF_CONTROL
pl_ccd_get_preflash
PARAM_PREFLASH
pl_ccd_get_premask
PARAM_PREMASK
pl_ccd_get_prescan
PARAM_PRESCAN
pl_ccd_get_ser_size
PARAM_SER_SIZE
pl_ccd_get_serial_num
PARAM_SERIAL_NUM
pl_ccd_get_summing_well
PARAM_SUMMING_WELL
pl_ccd_get_tmp
PARAM_TEMP (pl_get_param only)
pl_ccd_get_tmp_range
PARAM_TEMP_SETPOINT (from the
attributes of the get you can get the min
and max allowed temperature settings)
pl_ccd_get_tmp_setpoint
PARAM_TEMP_SETPOINT
pl_ccd_set_adc_offset
PARAM_ADC_OFFSET
pl_ccd_set_clear_cycles
PARAM_CLEAR_CYCLES
pl_ccd_set_clear_mode
PARAM_CLEAR_MODE
pl_ccd_set_pmode
PARAM_PMODE
pl_ccd_set_preamp_off_control
PARAM_PREAMP_OFF_CONTROL
pl_ccd_set_tmp_setpoint
PARAM_TEMP_SETPOINT
pl_ccs_get_status
PARAM_CCS_STATUS
pl_shtr_get_close_dly
PARAM_SHTR_CLOSE_DELAY
pl_shtr_get_open_dly
PARAM_SHTR_OPEN_DELAY
pl_shtr_get_open_mode
PARAM_SHTR_OPEN_MODE
pl_shtr_get_status
PARAM_SHTR_STATUS
pl_shtr_set_close_dly
PARAM_SHTR_CLOSE_DELAY
pl_shtr_set_open_dly
PARAM_SHTR_OPEN_DELAY
pl_shtr_set_open_mode
PARAM_SHTR_OPEN_MODE
pl_spdtab_get_bits
PARAM_BIT_DEPTH
pl_spdtab_get_entries
PARAM_SPDTAB_INDEX with ATTR_MAX
pl_spdtab_get_max_gain
PARAM_GAIN_INDEX with ATTR_MAX
pl_spdtab_get_port
PARAM_READOUT_PORT
Appendix B: Obsolete Functions
Obsolete Class 2 Function
pl_set_param/pl_get_param Equivalent
pl_spdtab_get_port_total
PARAM_READOUT_PORT with
ATTR_COUNT
pl_spdtab_get_time
PARAM_PIX_TIME
pl_spdtab_get_gain
PARAM_GAIN_INDEX
pl_spdtab_get_num
PARAM_SPDTAB_INDEX
pl_spdtab_set_gain
PARAM_GAIN_INDEX
pl_spdtab_set_num
PARAM_SPDTAB_INDEX
Table 8. Obsolete Class 3 Functions and Their pl_set_param/pl_set_param Equivalents
Obsolete Class 3 Function
pl_set_param/pl_get_param Equivalent
pl_exp_check_progress
pl_exp_get_time_seq
PARAM_EXP_TIME
pl_exp_set_time_seq
PARAM_EXP_TIME
pl_exp_set_cont_mode
135
136
PVCAM Manual
Version 2.7
Obsolete Class 0 Functions
PVCAM
Class 0: Camera Communications
pl_dd_get_info(0)
NAME
pl_dd_get_info — reads text information about the current device driver.
SYNOPSIS
rs_bool
pl_dd_get_info(int16 hcam,int16 bytes,char_ptr text)
DESCRIPTION
This function returns information from the current device driver (specified by
hcam ) including unusual conditions and special information. Since the
information may change from system to system, it is presented as unformatted
text. The input string text must be allocated to be at least bytes characters long.
No more than bytes characters are written into the string text. The size of the
complete message can be obtained from the associated parameter id
PARAM_DD_INFO_LENGTH.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
parameter id PARAM_DD_INFO_LENGTH
NOTES
On many systems, there is not a message. If there is not a message, parameter id
PARAM_DD_INFO_LENGTH returns a length of 0.
Appendix B: Obsolete Functions
137
PVCAM
Class 0: Camera Communications
pl_dd_get_info_length(0)
NAME
pl_dd_get_info_length — returns length of info message.
SYNOPSIS
rs_bool
pl_dd_get_info_length(int16 hcam,int16_ptr bytes)
DESCRIPTION
This is a companion to the pl_dd_get_info function, which returns an
information message for each device, as specified by hcam. This function returns
the length of that message, in the variable bytes.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_dd_get_info(0)
NOTES
Many devices have no message. In other words, they return a value of 0 for
bytes.
138
PVCAM Manual
Version 2.7
PVCAM
Class 0: Camera Communications
pl_dd_get_retries(0)
NAME
pl_dd_get_retries — reads the maximum number of command
retransmission attempts that are allowed.
SYNOPSIS
rs_bool
pl_dd_get_retries(int hcam,uns16_ptr max_retries)
DESCRIPTION
When a command or status transmission is garbled, the system signals for a
retransmission. After a certain number of failed transmissions (an initial attempt
+ max_retries), the system abandons the attempt and concludes that the
communications link has failed. The camera won't close, but the command or
status read returns with an error. The maximum number of retries is initially set
by the device driver, and is matched to the communications link, hardware
platform, and operating system. It may also be reset by the user. hcam must be a
valid camera handle.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_dd_set_retries(0),pl_dd_get_timeout(0),pl_dd_set_timeo
ut(0)
NOTES
When the camera is initially opened, the driver uses a default timeout and
max_retries. These numbers, representing reasonable values, were
specifically set for that communications link, hardware platform, and operating
system. Those values can be examined by calling pl_dd_get_timeout and
pl_dd_get_retries. Both of these values can be changed, but only after the
camera has successfully opened. If both numbers are known, the worst-case
device driver response may be approximated. See pl_dd_set_timeout for a
discussion.
The number of retries applies to status communications as well as commands. In
other words, if the camera electronics unit sends status data, but the message is
garbled, the device driver requests a retransmission. Max_retries sets the
upper limit to the number of retransmissions that will be requested.
Appendix B: Obsolete Functions
139
PVCAM
Class 0: Camera Communications
pl_dd_set_retries(0)
NAME
pl_dd_set_retries — sets the maximum command retry count.
SYNOPSIS
rs_bool
pl_dd_set_retries(int hcam,uns16 max_retries)
DESCRIPTION
When a command or status transmission is garbled, the system signals for a
retransmission. After a certain number of failed transmissions (the initial
transmission plus max_retries), the system abandons the attempt and
concludes that the communications link has failed. The camera won't close, but
the command or status read returns with an error. This command sets the number
of allowable retries, before an error is generated. hcam must be a valid camera
handle.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_dd_get_retries(0),pl_dd_get_timeout(0),pl_dd_set_timeo
ut(0)
NOTES
When the camera is initially opened, the driver uses a default timeout and
max_retries. These numbers were specifically set for that communications
link, hardware platform, and operating system, and represent reasonable values.
Those values may be examined by calling pl_dd_get_timeout and
pl_dd_get_retries, and they can both be changed, but only after the camera
has successfully opened. If both numbers are known, the worst-case device
driver response may be approximated. See pl_dd_set_timeout for a
discussion.
Setting max_retries to 0 is theoretically reasonable, but in practice, many
systems, such as SCSI, require retries.
140
PVCAM Manual
Version 2.7
PVCAM
Class 0: Camera Communications
pl_dd_get_timeout(0)
NAME
pl_dd_get_timeout — reads the maximum time the driver waits for
acknowledgment.
SYNOPSIS
rs_bool
pl_dd_get_timeout(int hcam,uns16_ptr m_sec)
DESCRIPTION
When hcam is a valid camera handle, this function reads the slowest allowable
response speed from the camera. This is a crucial factor used in the device driver
for communications control. If the driver sends a command to the camera, and
doesn't receive acknowledgment within m_sec milliseconds, the driver times out
and returns an error. Unless reset by the user, this time out is a default setting
that is contained in the device driver, and is matched to the communications link,
hardware platform, and operating system.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_dd_set_timeout(0),pl_dd_get_retries(0),pl_dd_set_retri
es(0)
NOTES
When the camera is initially opened, the driver uses a default timeout and
max_retries. These numbers, representing reasonable values, were
specifically set for that communications link, hardware platform, and operating
system. Those values can be examined by calling pl_dd_get_timeout and
pl_dd_get_retries. They can both be changed, but only after the camera
has successfully opened.
Appendix B: Obsolete Functions
141
PVCAM
Class 0: Camera Communications
pl_dd_set_timeout(0)
NAME
pl_dd_set_timeout — sets the worst-case communications response.
SYNOPSIS
rs_bool
pl_dd_set_timeout(int hcam,uns16 m_sec)
DESCRIPTION
When hcam is a valid camera handle, this function sets the slowest allowable
response speed from the camera. This is a crucial factor in device driver
communications. If the driver sends a command to the camera, and doesn't
receive some sort of acknowledgment within m_sec milliseconds, the driver
times out and returns with an error.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_dd_get_timeout(0),pl_dd_get_retries(0),pl_dd_set_retri
es(0)
NOTES
When the camera is initially opened, the driver uses a default timeout and
max_retries. These numbers, representing reasonable values, were specifically
set for that communications link, hardware platform, and operating system.
Those values may be examined by immediately calling pl_dd_get_timeout
and pl_dd_get_retries. They can both be changed, but only after the
camera has successfully opened.
Changing timeout does not mean that each driver call returns within m_sec
milliseconds. Retries and other factors must be considered. The driver then sends
the command again. Timeout only applies to each send-acknowledge cycle.
The worst-case driver dead time would be given by
timeout * (max_retries+1) + overhead
where overhead may involve minor but unpredictable effects like time slicing,
system latency, communications turn around, and driver housekeeping.
When setting timeout, it is usually wise to set things a little higher than
expected. When waiting for a response, a few milliseconds extra is not
catastrophic, but terminating prematurely may be.
142
PVCAM Manual
Version 2.7
PVCAM
Class 0: Camera Communications
pl_dd_get_ver(0)
NAME
pl_dd_get_ver — returns current device driver version number.
SYNOPSIS
rs_bool
pl_dd_get_ver (int16 hcam, uns16_ptr version)
DESCRIPTION
This returns a version number for the device driver used to access the camera
hcam. The version is a formatted hexadecimal number, of the style:
low byte
high byte
major version
------------
-------------
hi nibble
low nibble
minor version
trivial version
For example, the number 0xB1C0 indicates major release 177, minor release 12,
and trivial change 0.
A major release is defined as anything that alters the user interface, calling
sequence, or parameter interpretation of any device driver interface function
(anything that would alter the driver's API). A new major release often requires
the calling software to change, but wherever possible, major releases are
backward compatible with earlier releases.
A minor release should be completely transparent to higher level software, but
may include internal enhancements. A trivial change is reserved for use by the
software staff to keep track of extremely minor variations. The last digit may
also be used to flag versions of the driver constructed for unique customers or
situations. Minor and trivial releases should require no change in the calling
software.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_ddi_get_ver(0),pl_pvcam_get_ver(0)
NOTES
Open the camera before calling this function. Note that different cameras on the
same system may use different drivers. Thus, each camera can have its own
driver, and its own driver version.
Appendix B: Obsolete Functions
143
Obsolete Class 2 Functions
PVCAM
Class 2: Configuration/Setup
pl_ro_get_value(2)
NAME
pl_ro_get_value — gets a read-only value from the camera hardware.
SYNOPSIS
rs_bool
pl_ccd_get_chip_name(int16 hcam, char_ptr chip_name )
pl_ccd_get_color_mode (int16 hcam, uns16_ptr color_mode)
pl_ccd_get_cooling_mode(int16 hcam, int16_ptr
cooling_mode)
pl_ccd_get_frame_capable(int16 hcam, rs_bool_ptr
frame_capable)
pl_ccd_get_fwell_capacity(int16 hcam, uns32_ptr
fwell_capacity )
pl_ccd_get_mpp_capable(int16 hcam, int16_ptr mpp_capable )
pl_ccd_get_par_size(int16 hcam, uns16_ptr par_size )
pl_ccd_get_pix_par_dist(int16 hcam, uns16_ptr
pix_par_dist)
pl_ccd_get_pix_par_size(int16 hcam, uns16_ptr
pix_par_size)
pl_ccd_get_pix_ser_dist(int16 hcam, uns16_ptr
pix_ser_dist)
pl_ccd_get_pix_ser_size(int16 hcam, uns16_ptr
pix_ser_size)
pl_ccd_get_postmask(int16 hcam, uns16_ptr postmask )
pl_ccd_get_postscan(int16 hcam, uns16_ptr postscan )
pl_ccd_get_preamp_dly(int16 hcam, uns16_ptr preamp_dly )
pl_ccd_get_preflash(int16 hcam, uns16_ptr preflash )
pl_ccd_get_premask(int16 hcam, uns16_ptr premask )
pl_ccd_get_prescan(int16 hcam, uns16_ptr prescan )
pl_ccd_get_ser_size(int16 hcam, uns16_ptr ser_size )
pl_ccd_get_serial_num(int16 hcam, uns16_ptr serial_num )
pl_ccd_get_summing_well(int16 hcam, rs_bool_ptr
s_well_exists)
pl_ccd_get_tmp(int16 hcam, int16_ptr cur_tmp )
pl_ccd_get_tmp_range(int16 hcam, int16_ptr
tmp_hi_val,int16_ptr tmp_lo_val )
pl_ccs_get_status(int16 hcam, int16_ptr ccs_status )
pl_shtr_get_status(int16 hcam, int16_ptr shtr_status )
144
PVCAM
PVCAM Manual
Class 2: Configuration/Setup
Version 2.7
pl_ro_get_value(2)
pl_spdtab_get_bits(int16 hcam, int16_ptr spdtab_bits )
pl_spdtab_get_entries(int16 hcam, int16_ptr
spdtab_entries)
pl_spdtab_get_max_gain(int16 hcam, int16_ptr
spdtab_max_gain)
pl_spdtab_get_port(int16 hcam, int16_ptr spdtab_port )
pl_spdtab_get_port_total(int16 hcam, int16_ptr
total_ports )
pl_spdtab_get_time(int16 hcam, uns16_ptr spdtab_time )
DESCRIPTION
When the camera is configured at the factory, it is preset with values based on
the CCD specifications, characterization tests, and other sources. Some of these
functions return information directly from the camera head memory. Some
functions return dynamic conditions (such as temperature) while other settings
are based on several inputs. In all cases, the hcam parameter indicates the piece
of hardware from which the information is read. hcam must be a valid camera
handle obtained from pl_cam_open.
All of these variables are read-only – they are informational parameters and
cannot be reset. The read/write parameters are documented under
pl_rw_get_values and pl_values_set.
The full list of parameters and their meanings are:
chip_name
The name of the CCD. The name is a null-terminated text string. The user must
pass in a character array that is at least CCD_NAME_LEN elements long.
ccs_status
This variable holds sixteen bits of status data from the Camera Control
Subsystem. Only the lowest 2 bits are currently implemented. These 2 bits
(ccs_status & 0x03) give the status of the CCS:
Value
CCS State
0
idle
1
initializing
2
running
3
continuously clearing
A running state occurs any time the CCS is in the process of performing a
camera operation (including opening or closing the shutter, exposing, clearing
the CCD before a sequence or exposure, parallel or serial shifting, and
readout/digitization). After the CCD has finished reading out, the setup
determines if the CCS goes to idle or enters continuous clearing mode.
color_mode
The color mode of the CCD. Where 0 = mono and 1 = color mosaic RGGB.
This value is stored in the pv_cam_reads structure.
Appendix B: Obsolete Functions
145
PVCAM
Class 2: Configuration/Setup
pl_ro_get_value(2)
cooling_mode
This is the type of cooling used by the current camera. The value returned will
be one of the following constants:
NORMAL_COOL – This is an air or water-cooled system.
CRYO_COOL – The camera has an attached Dewar.
cur_tmp
This reads the current temperature of the CCD in C°x 100. For example, a
temperature of -35° would be read as -3500. Note that this returns the
measured temperature, not the setpoint (which is reported in
pl_ccd_get_tmp_setpoint.)
frame_capable
If true, this camera can run in frame transfer mode (set through
pl_ccd_set_pmode).
fwell_capacity
The full-well capacity of this CCD, measured in electrons.
mpp_capable
Indicates whether this CCD runs in MPP mode. The actual value returned is
equal to one of the following four constants:
MPP_UNKNOWN
MPP_ALWAYS_ON
MPP_ALWAYS_OFF
MPP_SELECTABLE
par_size
Parallel size of the CCD, in active rows. The full size of the parallel register is
actually ( par_size + premask + postmask).
pix_par_size
Size of the active area of a pixel, in the parallel direction, measured in
nanometers.
pix_par_dist
Center-to-center distance between pixels (in the parallel direction) measured in
nanometers. This is identical to pix_par_size, if there are no interpixel dead
areas.
pix_ser_size
Size of a single pixel’s active area, in the serial direction, measured in
nanometers.
pix_ser_dist
Center-to-center distance between pixels (in the serial direction), in nanometers.
This is identical to pix_ser_size, if there are no dead areas.
postmask
The number of masked lines at the far end of the parallel register (away from
the serial register). This is the number of additional parallel shifts which needs
to be done after readout to clear the parallel register.
postscan
Number of pixels to discard from the serial register after the last real data pixel.
These must be read or discarded to clear the serial register.
preflash
The number of milliseconds needed to illuminate the CCD using the flash diode
ring before an exposure, dark, or bias.
146
PVCAM Manual
Version 2.7
PVCAM
Class 2: Configuration/Setup
pl_ro_get_value(2)
premask
The number of masked lines at the near end of the parallel register, next to the
serial register. 0=no mask (no normal mask). If the premask is equal to
par_size, this probably indicates a frame transfer device with an ordinary
mask. Accordingly, the CCD should probably be run in frame transfer mode.
preamp_dly
Number of milliseconds required for the CCD output preamp to stabilize, after
it is turned on.
prescan
Number of pixels discarded from the serial register before the first real data
pixel.
s_well_exists
If true, this CCD includes a summing well.
serial_num
This is the serial number of the camera head (not the electronics unit).
ser_size
Serial size of the CCD active area, in pixels.
shtr_status
The current state of the camera shutter (actually, the current state of the driver
voltage to the shutter). The returned value will be equal to one of the following
constants: SHTR_OPENING,SHTR_OPEN,SHTR_CLOSED,SHTR_CLOSING,
or SHTR_FAULT. If the shutter is run too fast, it will overheat and trigger
SHTR_FAULT. The shutter electronics will disconnect until the temperature
returns to a suitable range. Note that even though the electronics have reset the
voltages to open or close the shutter, there is a lag time for the physical
mechanism to respond. See pl_shtr_get_open_dly and
pl_shtr_get_close_dly in the pl_rw_get_value function list.
spdtab_bits
Number of bits output by the currently selected speed choice. Although this
number might range between 6 and 16, the data will always be returned in an
unsigned 16-bit word. This value indicates the number of valid bits within that
word.
spdtab_entries
The number of entries in the speed table. Valid entries range from 0 to
spdtab_entries-1 (inclusive). The current selection may be altered through
pl_spdtab_set_num. Zero entries is possible and indicates that there are no
valid speeds that span the requirements of the camera head video board, A/D
board, communication channel, and host throughput.
spdtab_max_gain
This reports the maximum gain index setting for the current speed selection, not
the actual gain. The minimum gain index is always 1. The maximum gain index
is usually 16.
spdtab_port
This reports on the CCD readout port being used by the currently selected
speed. Different readout ports (used for alternate speeds) flip the image in X, Y,
or both.
Appendix B: Obsolete Functions
147
PVCAM
Class 2: Configuration/Setup
pl_ro_get_value(2)
spdtab_time
This is the actual speed for the currently selected speed choice. It returns the
time for each pixel, in nanoseconds. This can be converted to a camera speed in
kiloHertz through the following formula:
106
camera_speed (kHz) =
pixel_time (nanoseconds)
This readout time will change as new speed choices are selected.
tmp_hi_val
tmp_lo_val
These two values contain the legal range for temperature settings (using the
pl_ccd_set_tmp_setpoint command) in hundredths of degrees Celsius.
Any number inside this range is legal and will be accepted (-3500 = -35°C).
Numbers outside the range are ignored. However, just because a temperature is
legal does not mean it is possible. The environment and circumstances will
dramatically affect which temperatures can be achieved. An air-cooled camera
in Antarctica will be able to reach much lower temperatures than a water-cooled
camera in the Sahara.
total_ports
1, 2, 3, or 4. The number of ports on the system. This affects the CCS program,
but most users will probably not care since multi-port operation is transparent at
the level of PVCAM.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_rw_value(2),pl_set_value(2),pl_cam_open(2),
pl_cam_close(2)
NOTES
PVCAM interfaces to some cameras that do not support the full PVCAM
features or variable set. If the user attempts to get a variable that doesn't exist,
the system may either synthesize a value (based on available information) or
return an error.
148
PVCAM Manual
Version 2.7
PVCAM
Class 2: Configuration/Setup
pl_rw_get_value(2)
NAME
pl_rw_get_value— returns a read/write value from the camera hardware.
SYNOPSIS
rs_bool
pl_ccd_get_adc_offset (int16 hcam, int16_ptr offset)
pl_ccd_get_clear_cycles (int16 hcam, uns16_ptr
clear_cycles)
pl_ccd_get_clear_mode (int16 hcam,int16_ptr
clear_mode)
pl_ccd_get_pmode (int16 hcam, int16_ptr pmode)
pl_ccd_get_preamp_off_control (int16 hcam, uns32_ptr
preamp_off_control)
pl_ccd_get_tmp_setpoint (int16 hcam,int16_ptr tmp_setpoint)
pl_shtr_get_close_dly (int16 hcam, uns16_ptr shtr_close_dly)
pl_shtr_get_open_dly(int16 hcam, uns16_ptr shtr_open_dly)
pl_shtr_get_open_mode (int16 hcam,int16_ptr shtr_open_mode)
pl_spdtab_get_gain (int16 hcam,int16_ptr spdtab_gain)
pl_spdtab_get_num (int16 hcam,int16_ptr spdtab_num)
DESCRIPTION
These functions are very similar. Each returns operating conditions and variables
from the camera hardware. The hcam parameter indicates from which piece of
hardware to read the setting, and must be a valid camera handle obtained from
pl_cam_open.
This set of variables is read/write – all values may be altered and written to the
hardware. The write functions are nearly identical, except that they begin with
set_, and accept non-pointer arguments. A more extensive set of read-only
values are documented under the pl_ro_get_value heading.
The full list of parameters and their meaning is listed under pl_set_values.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_ro_get_value(2),pl_cam_open(2),pl_cam_close(2)
NOTES
PVCAM interfaces to some cameras that do not support the full PVCAM
features or variable set. If the user attempts to get a variable that doesn't exist, the
system may either synthesize a value (based on available information) or return
an error.
Appendix B: Obsolete Functions
149
PVCAM
Class 2: Configuration/Setup
NAME
pl_set_value — sets a value in the camera hardware.
SYNOPSIS
rs_bool
pl_ccd_set_adc_offset (int16 hcam, int16 offset)
pl_ccd_set_clear_cycles (int16 hcam, uns16
pl_set_value(2)
clear_cycles)
pl_ccd_set_clear_mode (int16 hcam, int16 clear_mode)
pl_ccd_set_pmode(int16 hcam, int16 pmode)
pl_ccd_set_preamp_off_control (int16 hcam, uns32
preamp_off_control)
pl_ccd_set_tmp_setpoint (int16 hcam,int16 tmp_setpoint)
pl_shtr_set_close_dly (int16 hcam, uns16 shtr_close_dly)
pl_shtr_set_open_dly (int16 hcam, uns16 shtr_open_dly)
pl_shtr_set_open_mode (int16 hcam, int16 shtr_open_mode)
pl_spdtab_set_gain (int16 hcam, int16 spdtab_gain)
pl_spdtab_set_num (int16 hcam, int16 spdtab_num)
DESCRIPTION
These functions set operating conditions and variables in the camera hardware.
The hcam parameter indicates which piece of hardware to apply the setting to,
and must be a valid camera handle obtained from pl_cam_open. A camera
handle of 0 (normally an invalid handle) will simultaneously send the setting to
all open cameras (if this is possible).
A complementary set of functions allows all of these values to be read back from
the hardware. They are documented under pl_rw_get_values. Many of these
settings are also dependent on ranges or capabilities documented in the
pl_ro_get_values functions, such as pl_ccd_get_frame_capable and
pl_ccd_get_tmp_range.
The full list of parameters and their meanings are:
clear_cycles
This is the number of times the CCD must be cleared to completely remove
charge from the parallel register.
150
PVCAM Manual
Version 2.7
PVCAM
Class 2: Configuration/Setup
pl_set_value(2)
clear_mode
clear_mode defines when clearing takes place:
CLEAR_NEVER
Don't ever clear the CCD.
CLEAR_PRE_EXPOSURE
Clear clear_cycles times before each
exposure starts.
CLEAR_PRE_SEQUENCE
Clear clear_cycles times before the
sequence starts.
CLEAR_POST_SEQUENCE
Do continuous clearing after the sequence
ends.
CLEAR_PRE_POST_SEQUENCE
Clear clear_cycles times before the
sequence starts and continuous clearing
after the sequence ends.
CLEAR_PRE_EXPOSURE_POST_SEQ Clear clear_cycles times before each
exposure starts and continuous clearing
after the sequence ends.
The CLEAR_NEVER setting is particularly useful for performing a readout after
an exposure has been aborted.
Note that normally during the idle period, the CCS parallel clock drivers and
serial drivers revert to a low power state. This saves on both power and heat. If
any CLEAR_..._POST options are used, these systems will not enter low power
mode. This will generate extra heat in both the electronics unit and the camera
head.
offset
This allows the user to determine the bias offset voltage. Accepts a signed 16-bit
argument: the new bias voltage to be set; returns a signed 16-bit value listing the
bias offset voltage. The units do not correspond to the output pixel values in any
simple fashion (the conversion rate should be linear, but may differ from system
to system) but a lower offset voltage will yield a lower value for all output
pixels. Pixels brought below zero by this method will be clipped at zero. Pixels
raised above saturation will be clipped at saturation. Plainly, before users can
alter the offset level, they must read the current offset level. The default offset
level will also vary from system to system and may change with each speed and
gain setting.
pmode
This allows the user to select the parallel clocking method. The following list
includes all valid constants:
PMODE_NORMAL
PMODE_FT_MPP
PMODE_ALT_FT
PMODE_MPP
PMODE_ALT_NORMAL
PMODE_ALT_FT_MPP
PMODE_FT
PMODE_ALT_MPP
where FT indicates frame transfer mode, FT_MPP indicates both frame transfer
and MPP mode. ALT indicates that custom parameters may be loaded.
preamp_off_
control
This is the exposure time limit in milliseconds above which the preamp is turned
off during exposure.
Appendix B: Obsolete Functions
151
PVCAM
Class 2: Configuration/Setup
pl_set_value(2)
shtr_close_dly
The shutter close delay. This is the number of milliseconds required for the
shutter to close. The software default values compensate for the standard
Photometrics shutter that is shipped with all cameras. You only need to set this
value if you are using a shutter with characteristics that differ from the standard
shutter. Valid inputs are any number in the range 0 to 65535 milliseconds.
shtr_open_dly
The shutter open delay. This is the number of milliseconds required for the
shutter to open. The software default values compensate for the standard
Photometrics shutter that is shipped with all cameras. You only need to set this
value if you are using a shutter with characteristics that differ from the standard
shutter. Valid inputs are any number in the range 0 to 65535 milliseconds.
shtr_open_mode
Shutter opening conditions, set to one of the following
OPEN_NEVER
The shutter closes before the exposure and stays closed
during the exposure.
OPEN_PRE_EXPOSURE
Opens each exposure. Normal mode.
OPEN_PRE_SEQUENCE
Opens the shutter at the start of each sequence. Useful
for frame transfer and external strobe devices.
OPEN_PRE_TRIGGER
If using a triggered mode, this function causes the
shutter to open before the external trigger is armed. If
using a non-triggered mode, this function operates
identical to OPEN_PRE_EXPOSURE.
OPEN_NO_CHANGE
Sends no signals to open or close the shutter. Useful for
frame transfer when you want to open the shutter and
leave it open (see pl_exp_abort).
spdtab_gain
The new gain setting for the current speed choice. The valid range for a gain
setting is 1 through spdtab_max_gain, where the max gain may be as high as
16. Values outside this range will be ignored. Note that gain settings may not be
linear! Values 1-16 may not correspond to 1x - 16x, and there are holes between
the values. However, when the camera is initialized, and every time a new speed
is selected, the system will always reset to run at a gain of 1x.
spdtab_num
This selects the CCD readout speed from a table of available choices. Entries
may range from 0 to spdtab_entries - 1. This setting affects all other
_spdtab_ values including spdtab_bits, spdtab_gain,
spdtab_max_gain ,spdtab_time, and spdtab_port. After this call,
the gain setting always resets to a value that corresponds to 1x. To use a gain
other than 1x, pl_spdtab_set_gain must be called after
pl_spdtab_set_num.
152
PVCAM Manual
Version 2.7
PVCAM
Class 2: Configuration/Setup
pl_set_value(2)
tmp_setpoint
This sets the desired CCD temperature in hundredths of degrees Celsius (-35 °C
is represented as -3500). The hardware attempts to heat or cool the CCD to this
temperature. The min/max allowable temperatures are given by tmp_hi_val
and tmp_lo_val, from the pl_ccd_get_tmp_range function. Settings
outside this range are ignored. Note that this function only sets the desired
temperature. Even if the desired temperature is in a legal range, it still may be
impossible to achieve. If the ambient temperature is too high, it's difficult to get
much cooling on an air-cooled camera.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_ro_get_value(2),pl_rw_get_value(2),pl_cam_open(0),pl_c
am_close(0)
NOTES
PVCAM interfaces to some cameras that do not support the full PVCAM
features or variable set. If the user attempts to get a variable that doesn't exist, the
system may either synthesize a value (based on available information) or return
an error.
Appendix B: Obsolete Functions
153
Obsolete Class 3 Functions
PVCAM
Class 3: Data Acquisition
pl_exp_check_progress(3)
NAME
pl_exp_check_progress — checks the progress of the current exposure.
SYNOPSIS
rs_bool
pl_exp_check_progress(int16 hcam, int16_ptr status,
uns32_ptr byte_cnt)
DESCRIPTION
This function is similar to pl_exp_check_status except that it only returns
one of the following values:
EXPOSURE_IN_PROGRESS The data collection routines are active. They are
waiting for data to arrive, but none has arrived yet.
READOUT_IN_PROGRESS
The data collection routines are active. The data
has started to arrive.
READOUT_COMPLETE
All the expected data has arrived. Data collection
is complete, and the driver has returned to idle
state.
In order to detect errors during the acquisition process, you must use
pl_exp_check_status. byte_cnt points to the number of bytes of data that
have arrived so far (divide by two to get the number of pixels). This level of
feedback is unimportant to many users.
RETURN VALUE
TRUE means the progress was checked successfully. FALSE indicates a bad
handle or a problem communicating with the camera.
SEE ALSO
pl_exp_setup_seq(3),pl_exp_start_seq(3),
pl_exp_check_status(3)
NOTES
When using pl_exp_check_progress you could call it inside a loop with a
timeout. If the timeout expires, then you could call pl_exp_check_status to
determine if an error occurred (READOUT_FAILED).
154
PVCAM Manual
Version 2.7
PVCAM
Class 3: Data Acquisition
NAME
pl_exp_get_time_seq — only used with VARIABLE_TIMED_MODE, this
function returns the exposure time from the camera.
SYNOPSIS
rs_bool
pl_exp_get_time_seq(init16 hcam,uns16_ptr exposure_time)
DESCRIPTION
This is a companion function to pl_exp_set_time_seq. The two functions are
used to examine and change the exposure time in VARIABLE_TIMED_MODE.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_exp_set_time_seq(3),pl_exp_setup_seq(3),Exposure Mode
Constants(3)
NOTES
pl_exp_get_time_seq(3)
Appendix B: Obsolete Functions
155
PVCAM
Class 3: Data Acquisition
pl_exp_set_time_seq(3)
NAME
pl_exp_set_time_seq — only used with VARIABLE_TIMED_MODE, this
function sets the exposure time for the next sequence.
SYNOPSIS
rs_bool
pl_exp_set_time_seq(init16 hcam,uns16 exposure_time)
DESCRIPTION
This is a companion function to pl_exp_get_time_seq. The two functions
are used to examine and change the exposure time in VARIABLE_TIMED_MODE.
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_exp_get_time_seq(3),pl_exp_setup_seq(3),Exposure Mode
Constants(3)
NOTES
When using VARIABLE_TIMED_MODE, this function must be called before the
first sequence is run, because VARIABLE_TIMED_MODE ignores the exposure
time in the pl_exp_setup_seq.
156
PVCAM Manual
Version 2.7
PVCAM
Class 3: Data Acquisition
pl_exp_set_cont_mode(3)
NAME
pl_exp_set_cont_mode - sets circular buffer mode.
SYNOPSIS
rs_bool
pl_exp_set_cont_mode(int16 hcam, int16 mode)
DESCRIPTION
This function sets the mode of operation for the circular buffer. mode can be set
to either CIRC_OVERWRITE or CIRC_NO_OVERWRITE. This function must be
called before calling pl_exp_start_cont().
RETURN VALUE
TRUE for success, FALSE for a failure. Failure sets pl_error_code.
SEE ALSO
pl_exp_get_driver_buffer(3), pl_exp_start_cont(3),
pl_exp_check_cont_status(0), pl_exp_get_oldest_frame(3),
pl_exp_get_latest_frame(3),
pl_exp_unlock_oldest_frame(3), and pl_exp_stop_cont(3)
NOTES
Use the parameter id PARAM_CIRC_BUFFER with pl_get_param to see if the
system can perform circular buffer operations. The circular buffer is passed to
pl_exp_start_cont. The buffer is either allocated by your application or
obtained from the driver as a preallocated block of memory, using the
pl_exp_get_driver_buffer function.
Refer to Example 3: Circular Buffer in "Chapter 8" for two examples of code
for circular buffer operation.
This function has been replaced by pl_exp_setup_cont.
Index
_
_const_ptr type ...........................................................7
A
Allocation and saving, buffers.................................93
ANSI C library ..........................................................3
Arrays ........................................................................7
ATTR_ACCESS......................................................48
ATTR_AVAIL ........................................................48
ATTR_COUNT .......................................................49
ATTR_CURRENT ..................................................49
ATTR_DEFAULT...................................................49
ATTR_INCREMENT .............................................49
ATTR_MAX ...........................................................49
ATTR_MIN.............................................................49
ATTR_TYPE...........................................................49
B
Binning ......................................................................8
Bit depth ....................................................................5
Buffer handle ...........................................................94
Buffer manipulation ..............................................4, 93
Buffers .....................................................................24
BULB_MODE.............................................18, 57, 69
C
Camera
Communication ...............................................4, 27
handle ..................................................................94
speed......................................................................9
Camera settings .......................................................46
CCD
coordinates model .................................................7
orientation .............................................................7
readout port ...........................................................8
Circular buffers....... 13, 72, 73, 75, 77, 81, 83, 85, 90,
117, 119, 156
Class 0 Functions
list of ...................................................................27
pl_cam_check......................................................28
pl_cam_close.......................................................29
pl_cam_get_diags................................................30
pl_cam_get_name ...............................................31
pl_cam_get_total .................................................32
pl_cam_open .......................................................33
pl_ddi_get_ver.....................................................34
pl_pvcam_get_ver ...............................................35
pl_pvcam_init......................................................36
pl_pvcam_uninit..................................................37
Class 1 Functions
list of ...................................................................42
pl_error_code ......................................................43
pl_error_message ................................................44
Class 2 Functions
list of ...................................................................46
pl_enum_str_length.............................................52
pl_get_enum_param ............................................51
pl_get_param.......................................................48
pl_set_param .......................................................50
Class 3 Functions
list of ...................................................................67
pl_exp_abort........................................................79
pl_exp_check_cont_status...................................83
pl_exp_check_status............................................82
pl_exp_finish_seq ...............................................70
pl_exp_get_driver_buffer....................................71
pl_exp_get_latest_frame .....................................72
pl_exp_get_oldest_frame ....................................73
pl_exp_init_seq ...................................................74
pl_exp_setup_cont...............................................75
pl_exp_setup_seq ................................................76
pl_exp_start_cont ................................................77
pl_exp_start_seq..................................................78
pl_exp_stop_cont ................................................81
pl_exp_uninit_seq ...............................................84
pl_exp_unlock_oldest_frame ..............................85
pl_exp_unravel....................................................86
pl_io_clear_script_control...................................88
pl_io_script_control ............................................89
Class 4 Functions
list of ...................................................................93
pl_buf_alloc.........................................................95
pl_buf_free ..........................................................96
pl_buf_get_bits....................................................97
pl_buf_get_exp_date ...........................................98
pl_buf_get_exp_time...........................................99
pl_buf_get_exp_total.........................................100
pl_buf_get_img_bin ..........................................101
pl_buf_get_img_handle.....................................102
pl_buf_get_img_ofs ..........................................103
pl_buf_get_img_ptr...........................................104
pl_buf_get_img_size .........................................105
pl_buf_get_img_total ........................................106
pl_buf_get_size .................................................107
pl_buf_init .........................................................109
pl_buf_set_exp_date..........................................108
pl_buf_uninit .....................................................110
Clear modes .............................................................13
clear_mode ..............................................................55
157
158
PVCAM Manual
CLEAR_NEVER...............................................15, 55
CLEAR_NEVER (obsolete)..................................150
CLEAR_POST_SEQUENCE............................15, 55
CLEAR_POST_SEQUENCE (obsolete)...............150
CLEAR_PRE_EXPOSURE ..............................15, 55
CLEAR_PRE_EXPOSURE (obsolete) .................150
CLEAR_PRE_EXPOSURE_POST_SEQ ...............55
CLEAR_PRE_EXPOSURE_POST_SEQ (obsolete)150
CLEAR_PRE_EXPOSURE_POST_SEQUENCE..15
CLEAR_PRE_POST_SEQUENCE ..................15, 55
CLEAR_PRE_POST_SEQUENCE (obsolete) .....150
CLEAR_PRE_SEQUENCE ..............................15, 55
CLEAR_PRE_SEQUENCE (obsolete) .................150
Close delay ..............................................................19
Code examples
circular buffer............................................117, 119
Latest Frame Mode............................................117
Oldest Frame Mode...........................................119
pl_get_param & pl_get_enum_param ...............111
pl_param_set .....................................................115
standard mode acquisition .................................121
color mode ...............................................................55
Configuration/setup .............................................4, 45
Constants .................................................................94
Contact information...................................................1
Custom timing .........................................................11
Customer service .......................................................1
D
Data acquisition ....................................................4, 67
Data arrays.................................................................8
Defined types.............................................................5
Defining exposures ..................................................68
Display orientation ....................................................8
E
Error code list ........................................................123
Error conditions .......................................................41
Error reporting ......................................................4, 41
Example code
circular buffer............................................117, 119
Latest Frame Mode............................................117
Oldest Frame Mode...........................................119
pl_get_param & pl_get_enum_param ...............111
pl_set_param .....................................................115
standard mode acquisition .................................121
Exposure loops ........................................................20
Exposure mode constants ........................................69
Exposure modes.................................................13, 16
Exposure scripts.......................................................20
exposure_time..........................................................16
F
FLASH_MODE...........................................18, 57, 69
Frame transfer..........................................................10
Full lateral resolution.................................................8
Full-CCD image in buffer........................................24
Version 2.7
G
Gain ...........................................................................9
Get and Set Parameter Functions
pl_get_enum_param ............................................45
pl_get_param.......................................................45
pl_set_param .......................................................45
H
Handle .......................................................................6
hbuf..........................................................................94
hcam ........................................................................94
himg.........................................................................94
I
Image
array ....................................................................10
buffers .................................................................24
handle ..................................................................94
pointer .................................................................94
smear ...................................................................11
Include files ...............................................................6
Initialization functions.............................................27
buffer...................................................................93
Interline CCD ..........................................................10
K
Kinetics....................................................................10
L
Latest Frame Mode code example .........................117
Library classes ...........................................................4
M
master.h .................................................................5, 6
Multiple exposures in buffer....................................24
Multiple speed options...............................................9
N
Non-pointers ..............................................................7
O
Obsolete Class 0 Functions
pl_dd_get_info ..................................................136
pl_dd_get_info_length ......................................137
pl_dd_get_retries...............................................138
pl_dd_get_timeout.............................................140
pl_dd_get_ver....................................................142
pl_dd_set_retries ...............................................139
pl_dd_set_timeout .............................................141
Obsolete Class 2 Functions
pl_ccd_get_adc_offset.......................................148
pl_ccd_get_chip_name......................................143
pl_ccd_get_clear_cycles....................................148
pl_ccd_get_clear_mode.....................................148
pl_ccd_get_color_mode ....................................143
pl_ccd_get_cooling_mode ................................143
pl_ccd_get_frame_capable................................143
pl_ccd_get_fwell_capacity................................143
Index
Obsolete Class 2 Functions (cont.)
pl_ccd_get_mpp_capable ..................................143
pl_ccd_get_par_size ..........................................143
pl_ccd_get_pix_par_dist ...................................143
pl_ccd_get_pix_par_size...................................143
pl_ccd_get_pix_ser_dist....................................143
pl_ccd_get_pix_ser_size ...................................143
pl_ccd_get_pmode ............................................148
pl_ccd_get_postmask ........................................143
pl_ccd_get_postscan..........................................143
pl_ccd_get_preamp_dly ....................................143
pl_ccd_get_preamp_off_control .......................148
pl_ccd_get_preflash ..........................................143
pl_ccd_get_premask..........................................143
pl_ccd_get_prescan ...........................................143
pl_ccd_get_ser_size ..........................................143
pl_ccd_get_serial_num......................................143
pl_ccd_get_summing_well................................143
pl_ccd_get_tmp .................................................143
pl_ccd_get_tmp_range ......................................143
pl_ccd_get_tmp_setpoint ..................................148
pl_ccd_set_adc_offset .......................................149
pl_ccd_set_clear_cycles ....................................149
pl_ccd_set_clear_mode .....................................149
pl_ccd_set_pmode.............................................149
pl_ccd_set_preamp_off_control........................149
pl_ccd_set_tmp_setpoint...................................149
pl_ccs_get_status...............................................143
pl_ro_get_value.................................................143
pl_rw_get_value................................................148
pl_set_value.......................................................149
pl_shtr_get_close_dly........................................148
pl_shtr_get_open_dly ........................................148
pl_shtr_get_open_mode ....................................148
pl_shtr_get_status..............................................143
pl_shtr_set_close_dly ........................................149
pl_shtr_set_open_dly ........................................149
pl_shtr_set_open_mode.....................................149
pl_spdtab_get_bits.............................................143
pl_spdtab_get_entries........................................144
pl_spdtab_get_gain............................................148
pl_spdtab_get_max_gain...................................144
pl_spdtab_get_num ...........................................148
pl_spdtab_get_port ............................................144
pl_spdtab_get_port_total...................................144
pl_spdtab_get_time ...........................................144
pl_spdtab_set_gain ............................................149
pl_spdtab_set_num............................................149
Obsolete Class 3 Functions
pl_exp_check_progress .....................................153
pl_exp_get_time_seq.........................................154
pl_exp_set_cont_mode......................................156
pl_exp_set_time_seq .........................................155
Oldest Frame Mode code example ........................119
Open delay, close delay ...........................................19
OPEN_NEVER .................................................20, 65
159
OPEN_NEVER (obsolete).....................................151
OPEN_NO_CHANGE ......................................20, 65
OPEN_NO_CHANGE (obsolete) .........................151
OPEN_PRE_EXPOSURE.................................20, 65
OPEN_PRE_EXPOSURE (obsolete) ....................151
OPEN_PRE_SEQUENCE.................................20, 65
OPEN_PRE_SEQUENCE (obsolete)....................151
OPEN_PRE_TRIGGER ....................................20, 65
OPEN_PRE_TRIGGER (obsolete) .......................151
Orientation of CCD ...................................................7
P
Parallel.......................................................................7
Parallel binning..........................................................8
PARAM_ACCUM_CAPABLE ..............................53
PARAM_ADC_OFFSET ........................................53
PARAM_ANTI_BLOOMING ................................53
PARAM_BIT_DEPTH............................................53
PARAM_BOF_EOF_CLR ......................................90
PARAM_BOF_EOF_COUNT ................................90
PARAM_BOF_EOF_ENABLE ..............................90
PARAM_CAM_FW_VERSION.............................54
PARAM_CCS_STATUS ........................................54
PARAM_CHIP_NAME ..........................................54
PARAM_CIRC_BUFFER.......................................90
PARAM_CLEAR_CYCLES...................................54
PARAM_CLEAR_MODE ......................................55
PARAM_COLOR_MODE......................................55
PARAM_CONTROLLER_ALIVE.........................56
PARAM_COOLING_MODE .................................56
PARAM_CUSTOM_CHIP .....................................56
PARAM_CUSTOM_TIMING ................................56
PARAM_DD_INFO................................................38
PARAM_DD_INFO_LENGTH ..............................38
PARAM_DD_RETRIES .........................................38
PARAM_DD_TIMEOUT .......................................38
PARAM_DD_VERSION ........................................39
PARAM_EDGE_TRIGGER ...................................57
PARAM_EXP_MIN_TIME ....................................90
PARAM_EXP_RES ................................................90
PARAM_EXP_RES_INDEX..................................91
PARAM_EXP_TIME........................................16, 91
PARAM_EXPOSURE_MODE...............................57
PARAM_FRAME_CAPABLE ...............................57
PARAM_FTSCAN..................................................57
PARAM_FWELL_CAPACITY..............................57
PARAM_GAIN_INDEX.........................................57
PARAM_GAIN_MULT_ENABLE ........................58
PARAM_GAIN_MULT_FACTOR ........................58
PARAM_HEAD_SER_NUM_ALPHA ..................58
PARAM_HW_AUTOSTOP....................................91
PARAM_INTENSIFIER_GAIN.............................58
PARAM_IO_ADDR ...............................................58
PARAM_IO_BITDEPTH........................................58
PARAM_IO_DIRECTION .....................................58
PARAM_IO_STATE ..............................................59
160
PVCAM Manual
PARAM_IO_TYPE.................................................59
PARAM_KIN_WIN_SIZE......................................59
PARAM_LOGIC_OUTPUT ...................................59
PARAM_MIN_BLOCK..........................................60
PARAM_MPP_CAPABLE.....................................60
PARAM_NUM_MIN_BLOCK ..............................60
PARAM_NUM_OF_STRIPS_PER_CLR...............60
PARAM_PAR_SHIFT_TIME ................................60
PARAM_PAR_SIZE...............................................60
PARAM_PCI_FW_VERSION................................60
PARAM_PIX_PAR_DIST ......................................61
PARAM_PIX_PAR_SIZE ......................................61
PARAM_PIX_SER_DIST ......................................61
PARAM_PIX_SER_SIZE.......................................61
PARAM_PIX_TIME...............................................61
PARAM_PMODE ...................................................61
PARAM_POSTMASK............................................62
PARAM_POSTSCAN.............................................62
PARAM_PREAMP_DELAY..................................62
PARAM_PREAMP_OFF_CONTROL ...................62
PARAM_PREFLASH .............................................62
PARAM_PREMASK ..............................................62
PARAM_PRESCAN ...............................................62
PARAM_READOUT_PORT..................................63
PARAM_READOUT_TIME ..................................63
PARAM_SER_SHIFT_TIME.................................63
PARAM_SER_SIZE ...............................................63
PARAM_SERIAL_NUM........................................63
PARAM_SHTR_CLOSE_DELAY.........................64
PARAM_SHTR_CLOSE_DELAY_UNIT .............64
PARAM_SHTR_GATE_MODE ............................63
PARAM_SHTR_OPEN_DELAY ...........................64
PARAM_SHTR_OPEN_MODE.............................65
PARAM_SHTR_STATUS......................................65
PARAM_SKIP_AT_ONCE_BLK ..........................66
PARAM_SPDTAB_INDEX ...................................66
PARAM_SUMMING_WELL.................................66
PARAM_TEMP ......................................................66
PARAM_TEMP_SETPOINT..................................66
Parameter passing ......................................................7
pbin............................................................................8
pl_buf_alloc.............................................................95
pl_buf_free ..............................................................96
pl_buf_get_bits ........................................................97
pl_buf_get_exp_date ...............................................98
pl_buf_get_exp_time ...............................................99
pl_buf_get_exp_total .............................................100
pl_buf_get_img_bin...............................................101
pl_buf_get_img_handle .........................................102
pl_buf_get_img_ofs...............................................103
pl_buf_get_img_ptr ...............................................104
pl_buf_get_img_size .............................................105
pl_buf_get_img_total.............................................106
pl_buf_get_size......................................................107
pl_buf_init .............................................................109
pl_buf_set_exp_date..............................................108
Version 2.7
pl_buf_uninit .........................................................110
pl_cam_check ..........................................................28
pl_cam_close ...........................................................29
pl_cam_get_diags ....................................................30
pl_cam_get_name....................................................31
pl_cam_get_total .....................................................32
pl_cam_open............................................................33
pl_ccd_get_adc_offset (obsolete) ..........................148
pl_ccd_get_chip_name (obsolete) .........................143
pl_ccd_get_clear_cycles (obsolete) .......................148
pl_ccd_get_clear_mode (obsolete) ........................148
pl_ccd_get_color_mode (obsolete)........................143
pl_ccd_get_cooling_mode (obsolete) ....................143
pl_ccd_get_frame_capable (obsolete) ...................143
pl_ccd_get_fwell_capacity (obsolete) ...................143
pl_ccd_get_mpp_capable (obsolete)......................143
pl_ccd_get_par_size (obsolete) .............................143
pl_ccd_get_pix_par_dist (obsolete).......................143
pl_ccd_get_pix_par_size (obsolete) ......................143
pl_ccd_get_pix_ser_dist (obsolete) .......................143
pl_ccd_get_pix_ser_size (obsolete).......................143
pl_ccd_get_pmode (obsolete)................................148
pl_ccd_get_postmask (obsolete)............................143
pl_ccd_get_postscan (obsolete) .............................143
pl_ccd_get_preamp_dly (obsolete)........................143
pl_ccd_get_preamp_off_control (obsolete) ...........148
pl_ccd_get_preflash (obsolete)..............................143
pl_ccd_get_premask (obsolete) .............................143
pl_ccd_get_prescan (obsolete)...............................143
pl_ccd_get_ser_size (obsolete)..............................143
pl_ccd_get_serial_num (obsolete) .........................143
pl_ccd_get_summing_well (obsolete) ...................143
pl_ccd_get_tmp (obsolete).....................................143
pl_ccd_get_tmp_range (obsolete)..........................143
pl_ccd_get_tmp_setpoint (obsolete) ......................148
pl_ccd_set_adc_offset (obsolete)...........................149
pl_ccd_set_clear_cycles (obsolete)........................149
pl_ccd_set_clear_mode (obsolete).........................149
pl_ccd_set_pmode (obsolete) ........................148, 149
pl_ccd_set_preamp_off_control (obsolete) ...........149
pl_ccd_set_tmp_setpoint (obsolete) ......................149
pl_ccs_get_status (obsolete) ..................................143
pl_dd_get_info (obsolete)......................................136
pl_dd_get_info_length (obsolete) ..........................137
pl_dd_get_retries (obsolete) ..................................138
pl_dd_get_timeout (obsolete) ................................140
pl_dd_get_ver (obsolete) .......................................142
pl_dd_set_retries (obsolete)...................................139
pl_dd_set_timeout (obsolete).................................141
pl_ddi_get_ver.........................................................34
pl_enum_str_length .................................................52
pl_error_code.....................................................42, 43
pl_error_message...............................................42, 44
pl_exp_abort ............................................................79
pl_exp_check_cont_status .......................................83
pl_exp_check_progress (obsolete).........................153
Index
pl_exp_check_status................................................82
pl_exp_finish_seq....................................................70
pl_exp_get_driver_buffer ........................................71
pl_exp_get_latest_frame..........................................72
pl_exp_get_oldest_frame.........................................73
pl_exp_get_time_seq (obsolete) ............................154
pl_exp_init_seq........................................................74
pl_exp_set_cont_mode (obsolete) .........................156
pl_exp_set_time_seq (obsolete).............................155
pl_exp_setup_cont ...................................................75
pl_exp_setup_seq...............................................16, 76
pl_exp_start_cont.....................................................77
pl_exp_start_seq ..................................................8, 78
pl_exp_stop_cont.....................................................81
pl_exp_uninit_seq....................................................84
pl_exp_unlock_oldest_frame...................................85
pl_exp_unravel ........................................................86
pl_get_enum_param ................................................51
pl_get_param ...........................................................48
pl_io_clear_script_control .......................................88
pl_io_script_control.................................................89
pl_pvcam_get_ver ...................................................35
pl_pvcam_init ....................................................36, 45
pl_pvcam_uninit ......................................................37
pl_ro_get_value (obsolete) ....................................143
pl_rw_get_value (obsolete) ...................................148
pl_set_param............................................................50
pl_set_value (obsolete) ..........................................149
pl_shtr_get_close_dly (obsolete) ...........................148
pl_shtr_get_open_dly (obsolete) ...........................148
pl_shtr_get_open_mode (obsolete)........................148
pl_shtr_get_status (obsolete) .................................143
pl_shtr_set_close_dly (obsolete) ...........................149
pl_shtr_set_open_dly (obsolete) ............................149
pl_shtr_set_open_mode (obsolete) ........................149
pl_spdtab_get_bits (obsolete) ................................143
pl_spdtab_get_entries (obsolete) ...........................144
pl_spdtab_get_gain (obsolete) ...............................148
pl_spdtab_get_max_gain (obsolete) ......................144
pl_spdtab_get_port (obsolete) ...............................144
pl_spdtab_get_port_total (obsolete) ......................144
pl_spdtab_get_time (obsolete)...............................144
pl_spdtab_set_gain (obsolete) ...............................149
pl_spdtab_set_num (obsolete) ...............................149
PMODE_ALT_FT...................................................61
PMODE_ALT_FT (obsolete)................................150
PMODE_ALT_FT_MPP.........................................61
PMODE_ALT_FT_MPP (obsolete) ......................150
PMODE_ALT_MPP ...............................................61
PMODE_ALT_MPP (obsolete).............................150
161
PMODE_ALT_NORMAL ......................................61
PMODE_ALT_NORMAL (obsolete) ...................150
PMODE_FT ............................................................61
PMODE_FT (obsolete)..........................................150
PMODE_FT_MPP...................................................61
PMODE_FT_MPP (obsolete)................................150
PMODE_INTERLINE ............................................61
PMODE_KINETICS ...............................................61
PMODE_MPP .........................................................61
PMODE_MPP (obsolete) ......................................150
PMODE_NORMAL................................................61
PMODE_NORMAL (obsolete) .............................150
Pointers ......................................................................7
PVCAM.................................................................1, 3
pvcam.h .....................................................................6
R
Readout port selection ...............................................8
Region .......................................................................7
S
s,p coordinates ...........................................................7
sbin ............................................................................8
SDK ...........................................................................1
Sequence parameters ...............................................13
Sequences ................................................................13
Sequences in buffer .................................................24
Serial binning.............................................................8
Serial register.............................................................7
shtr_open_mode ......................................................65
Shutter open mode .............................................13, 20
Single exposure, multiple images in buffer .............24
Smearing..................................................................11
Source code example ...............................................25
Specifying regions .....................................................7
Speed choices ............................................................9
Standard shutter .......................................................19
Storage array............................................................10
STROBED_MODE .....................................17, 57, 69
Structures and arrays ..................................................7
System overview........................................................3
T
Technical support ......................................................1
TIMED_MODE...........................................16, 57, 69
TRIGGER_FIRST_MODE .........................17, 57, 69
V
VARIABLE_TIMED_MODE.....................16, 57, 69
Video coordinates ......................................................8
162
PVCAM Manual
This page intentionally left blank.
Version 2.7
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : Yes Encryption : Standard V2.3 (128-bit) User Access : Print, Extract, Print high-res Page Count : 168 Page Mode : UseOutlines Has XFA : No XMP Toolkit : XMP toolkit 2.9.1-14, framework 1.6 About : uuid:a6e44169-b886-4779-8612-ded61843faff Producer : Acrobat Distiller 6.0.1 (Windows) Creator Tool : Acrobat PDFMaker 6.0 for Word Modify Date : 2004:12:28 13:07:37-05:00 Create Date : 2004:12:20 10:40:30-05:00 Metadata Date : 2004:12:28 13:07:37-05:00 Document ID : uuid:44f6ac8d-eff9-4ac4-82bd-1569744c7374 Format : application/pdf Title : PVCAM 2.7 User Manual Creator : 4411-0094, Ver. 2.7, Rev 0 Description : Princeton Instruments, a division of Roper Scientific, Inc. Author : 4411-0094, Ver. 2.7, Rev 0 Subject : Princeton Instruments, a division of Roper Scientific, Inc.EXIF Metadata provided by EXIF.tools