CP40 Photon Counting Data Interface

Last modified: Tue Jul 16 17:43:36 METDST

Contents

File access

Introduction

This document deals with the CP40 Application Programming Interface (CP40 API) and the CP40 Graphic User Interface (CP40 GUI). The CP40 API is written both in C and Tcl (the Tcl part makes use of TiM and [incr Tcl] extensions) and is intended to provide the needed hooks to manage and process photon couting data. The CP40 GUI is written in Tcl/Tk (with Tix and TiM extensions) and provides an interactive interface to the CP40 API capabilities.

The CP40 camera is a photon counting image detector build by A. Blazit and R. Foy. Its name means Comptage de Photons and 40 is the diameter (in millimeters) of the entrance photocathode. The CP40 camera has 4 imaging channels and its current frame rate is 20 milliseconds. The photon counting data files consist in a header (which store editable attributes) followed by frames of photon event positions. The events from all channels are saved in the same file. The number of events per frame is variable. A photon counting data file should gather the data acquired during a continuous observation of a single object.

File access

You open a CP40 photon counting data file by:

    cp40data dataId fileName ?mode?

where dataId is a key which uniquely identifies the hook associated with the open data file, fileName is the name of the data file and the file access is given by the optional mode which is one of:

r or read

for read access (default if mode omitted): it is only possible to read data from the file; attributes can be modified (e.g., to change the preprocessing options) but cannot be saved.

u or update

for update access: the file must already exists, it is possible to modify and save data attributes and to append additional data to the end of the file.

w or write

for write access: a new data file is created (an error is raised if the file already exists) and it is possible to modify and save data attributes and to append additional data to the end of the file.

In fact, cp40data is an [incr Tcl] class: dataId is the name of the new object of this class created by the command cp40data. The special object name #auto can be used to automatically generate a unique new object name. The command

cp40data dataId fileName ...

opens the data file with specified access as explained above, but also returns the actual object name objName (i.e., dataId unless automatic name generation feature is used) and creates a new Tcl command named objName. This commands comes with several so-called methods to give access to object internals (e.g., data, properties).

Finally, a global Tcl array also named objName is created and filled with the current values of the data attributes.

Methods

Each CP40 data object is itself a Tcl command which provides several methods. The general syntax is:

objName method ?args ...?

Implemented methods are:

objName delete

Delete objName and release related resources. Regardless objName access mode, the file header is not updated. It is better to use method close which deals with header updating.

objName close ?-noupdate?

Delete objName and release related resources. If objName access mode is write or update, the file header is updated unless flag -noupdate is set.

objName readHeader

Read or reread file header. May be used to cancel current attribute settings and to restore the ones saved in header.

objName writeHeader

Write file header, this can be applied only if access mode is write or update. May be used to save current attribute settings in file header.

objName printAttributes ?fileId?

Print out contents of global Tcl variable objName into file fileId (default stdout).

objName saveAttributes fileName ?-include patterns? ?-exclude patterns? ?-selection? ?-preprocessing? ?-correction?

Save current attributes (i.e. contents of global Tcl array objName) in file fileName. Options -include and -exclude can be used to specify a list of patterns of attribute names to include or exclude, the arguments patterns are Tcl lists of glob-style patterns. An attribute name must match one of the include patterns and match none of the exclude patterns to be saved. If only include pattern list is specified no other names gets excluded. If only exclude pattern list is specified all other names gets included. If none of the include and exclude patterns are specified, one of the options -preprocessing, -correction, or -selection indicates to save all the pre-processing attributes, only the distortion correction ones or only the data selection ones. Without any options, the default is to save only distortion correction attributes. The textual attribues are first written into the file, so that it is possible to edit attribute file with a text editor.

objName restoreAttributes fileName ?-include patterns? ?-exclude patterns? ?-selection? ?-preprocessing? ?-correction?

Restore attributes from the ones saved in fileName. The same selection rules as for method saveAttributes can be used.

objName import -buffer expr -first|-last ?-number start? ?-trust?

objName import -file fileId -first|-last ?-number start? ?-trust?

Import raw photon counting data from buffer expr or file fileId. ObjName must be in write or update mode. One of the flags -first or -last must be present to indicate which photon is flagged to mark begin/end of frame. Flag trust indicates that the modulo 128 frame number can be trusted. The integer start sets the number of the first imported frame.

objName stat channel varName ?nframes?

Store into Tcl variable varName the statistics of objName data for channel number channel. If nframes is specified, only nframes are read; otherwise, all the remaining frames are read. Returns the actual number of frames processed.

objName it channel varName ?nframes?

Store into Tcl variable varName the long exposure image of objName data for channel number channel. If nframes is specified, only nframes are read; otherwise, all the remaining frames are read. Returns the actual number of frames processed.

objName ac channel varName ?nframes?

Store into Tcl variable varName the total autocorrelation of objName data for channel number channel. If nframes is specified, only nframes are read; otherwise, all the remaining frames are read. Returns the actual number of frames processed.

objName ic ch1 ch2 varName ?nframes?

Store into Tcl variable varName the total intercorrelation of objName data for channels number ch1 and ch2. If nframes is specified, only nframes are read; otherwise, all the remaining frames are read. Returns the actual number of frame processed. Since the two bottom channels are upside-down, it is not a good idea to compute intercorrelation between one of the top channels and one of the bottom channels with no distortion correction (the effective distortion correction coefficients are computed so as to turn the two bottom channels).

objName ict ch varName ?nframes?

Store into Tcl variable varName the total temporal intercorrelation of objName data for channel number ch. The time lag is set by the exposure attribute. If nframes is specified, only nframes are read; otherwise, all the remaining frames are read. Returns the actual number of frames processed.

objName read ch varName

objName read ch wName xName yName

The first form is equivalent to:

objName it ch varName 1

In the second form, store into Tcl variables wName xName and yName the weights, abscissae and ordinates of the photons of the next frame in objName data for channel number ch.

objName write ?-channel ch? img ...

objName write ?-channel ch? w x y ...

Write a new data frame into objName. Inputs are: a photon counting image img or the weights w, abscissae x and ordinates y of the photons. If the channel is specified by ch, coordinates are truncated to the raw pixel matrix depending on the current choice for the raw pixel resolution (i.e., 1, 1/2 or 1/4 CCD pixel), e.g., if the raw pixel resolution is set to 1 CCD pixel, the coordinates boundaries are: [0:383, 0:287]. If channel number is specified, several channels can be writen at the same time.

Data attributes

CP40 data attributes are stored into global Tcl array objName. Some of these attributes just give general information about the data contents or history, e.g., the following code fragment shows how to store such kind of information:

    global objName
    set objName(telescope)    "CFHT 3.60m"
    set objName(date)         "30/11/89 02:34:56"
    set objName(object)       "T Tauri"
    set objName(wavelength,1) "H alpha"
    set objName(wavelength,2) "continuum"

These textual attributes are saved into the file header when one of the methods writeHeader or close is called.

On the other hand, there are attributes which have an influence onto the way how photon counting data are processed. All these attributes are linked (via so-called Tcl traces) so that:

1. they get updated when needed, e.g., the objName(extreme) variable which gives the minimum and maximum photon positions after processing is updated each time one of the distortion correction attributes is modified;
2. each time their value is modifed (e.g., by the set Tcl command), the new value is checked (if it is not correct, an error is raised and the previous value is restored) and internal settings may be updated in order to account for the requested behaviour. For instance, the value of objName(correction) can be modified to indicates which method of distortion correction should be applied when reading photons.

The following figure summarizes linked CP40 objects attributes:
Changing the rotation angle objName(angle), the scaling factor objName(scale), the unscaled coefficients of distortion correction objName(rawcoef) or the method objName(correction) to apply for distortion correction forces the effective coefficients of distortion correction objName(coef) and the objName(extreme) boundaries to be recomputed and probably makes the objName(window) settings obsolete.

When linked attributes depends on the channel number, the attribute name is followed by a comma and the channel number as in objName(photons,channel), valid channel numbers are: 0, 1, 2 and 3. Other linked attributes apply globally (i.e., for all the channels).

objName(frames)

The total number of frames in data file. This attribute should not be modified.

objName(saturations)

The total number of saturations which occured during acquisition. This attribute should not be modified.

objName(photons,channel)

The total number of photons (in channel channel) into data file. This attribute should not be modified.

objName(exposure)

Number of successive 20 ms frames to pack together into a short-exposure frame. This attribute is only relevant in read mode. If exposure is greater than 1, the resulting super-frames will be overlapping: the time delay between successive super-frames is 20 ms.

objName(count)

The number of raw-photons in the frame buffer (these photons are unprocessed ones, all channel together). This attribute is read-only.

objName(number)

The actual frame number. This attribute is read-only (it may be changed by the import method).

objName(mode)

File access mode (for absent-minded people), one of: read, write or update. This attribute is read-only.

objName(scale)

Pixel scale after distortion correction in pixels per grid step (one grid step is the separation between adjacent spots produced by the calibration grid). This scaling is only effective if distortion correction is applied. Scale must be positive. If scale is zero, then effective distortion correction coefficients are set so that distortion correction do nothing but turn the channels 2 and 3.

objName(angle)

Rotation angle after distortion correction in degrees anti-clockwise (may be wrapped in the range (-180°:180°]). This rotation is only effective if distortion correction is applied.

objName(rawcoef)

Raw coefficients for distortion correction: a 20-by-4 element double precision floating point TiM expression (one row for each channel, coefficients are managed as a whole and cannot be accessed on a per channel basis). The raw coefficients are assumed to be unscaled (i.e., one pixel per grid step after distortion correction) and to let the two bottom channels unrotated.

objName(coef)

Effective coefficients for distortion correction: a 20-by-4 element double precision floating point TiM expression (one row for each channel, coefficients are managed as a whole and cannot be accessed on a per channel basis). The effective coefficients are read-only, they are computed from the values of the rawcoef, angle and scale attributes and they rotate the two bottom channels appropriately.

objName(correction)

Method to apply for distortion correction, one of:

none

no distortion correction.

simple

apply rounded to the closest pixel distortion correction.

random

apply random sub-pixel distortion correction.

weighted

apply weighted distortion correction.

objName(parity)

Parity of selected frames, one of:

any

use all frames.

even

use even numbered frames.

odd

use odd numbered frames.

objName(pixel)

Raw pixel resolution, one of:

1

use coordinates in units of CCD pixel, so-called physical pixel.

1/2

use coordinates in units of 1/2 CCD pixel

1/4

use coordinates in units of 1/4 CCD pixel, so-called logical pixel.

objName(spurious)

Name of method used to cope with spurious multiple photon-events, one of:

leave

do nothing special with spurious events.

delete

delete spurious events.

center

replace each group of spurious events by its barycenter.

single

replace each group of spurious events by the first of them.

objName(flux,channel)

Range for frame selection based on the flux level (i.e., the number of counts in a single frame): a Tcl list of 2 elements {min max} each one being an integer or the wild character * to indicate that this boundary is not subject to any restriction.

objName(distance,channel)

Range for frame selection based on the distance (in pixels) of the photo-center of the short exposure image with respect to the closest window edge.

objName(spread,channel)

Range for frame selection based on the spread (standard deviation with respect to the mean position of the events in pixels).

objName(ratio,channel)

Range for frame selection based on the ratio distance/spread.

objName(window,channel)

Boundaries to select photons from their position: a Tcl list of four elements {xmin xmax ymin ymax} each one being an integer or the wild character * to indicate that this boundary is not subject to any restriction.

objName(extreme,channel)

Extreme photon position values: a Tcl list of four integers {xmin xmax ymin ymax}. This attribute is read-only.

Per-channel attributes can be set to the same value for all channels by omitting the _ch (where ch is the channel number) at the end of the attribute name. This feature is intended to facilitate the reseting of ``per-channel'' attributes. For instance:

cp40api data1 set -window {* * * *}
cp40api data1 set -photons 0

reset the window to extreme values and set the photon count to zero for each channel of data referenced by key data1. The rawcoef attribute is an exception to this rule.

Getting per-channel attributes without specifying a channel number returns a list of 4 items: each of which is the current attribute value for one of the corresponding channel. The rawcoef and coef attributes are an exception to this rule. For instance:

% cp40api data1 get -spread spreadRanges
% set spreadRanges
{* 14.0} {* 15.0} {* *} {* 12.0}
% cp40api data1 get -photons photonCounts
% set photonCounts
11044 12865 43435 39789

Tcl CP40 API

This is the low-level Tcl commands used to manage photon counting data files. The basic user should not have to use these commands.

• cp40api new key fileId
  Create a new hook named key to handle a CP40 data file. The Tcl file fileId is attached to key with an access mode which depends on file permission of fileId. The fileId is the returned value of a call to: is fileId and mode is one of:

r

for read mode.

u

for update mode.

w

for write mode.

• cp40api delete key
  Destroy the CP40 data hook named key. The related file is not closed (use Tcl command close for that); likewise, the related Tcl array is not destroyed (use Tcl command unset key for that).
• cp40api names
  Return a list of all currently registered CP40 data keys.
• cp40api attributes ?type?
  Return a list of all CP40 attribute names. In order to limit the list to particular type of attributes Optional argument type can be one of coef, double, long, keyword, per_channel, range, read_only or window (these names follow conventions in cp40Int.h file).
• cp40api info key
  Return a list of contents of the CP40_Data structure in the form:
  {attribute1 value1} {attribute2 value2}...
  This produces more or less the same result as Tcl command array get key except that there are additional fields (addresses of file pointer, photon buffer, Tcl interprter, ...) and that values of distortion coefficients are converted into human readable strings.
• cp40api import dst -first|last -stream streamId ?options?
  cp40api import dst -first|last -buffer expr ?options?
  Import raw CP40 data. Options are: ?-count number? ?-trust? ?-start number?
• cp40api stat objName channel varName ?nFrames?
  
• cp40api it objName channel varName ?nFrames?
  
• cp40api ac objName channel varName ?nFrames?
  
• cp40api ic objName channel1 channel2 varName ?nFrames?
  
• cp40api read key channel arrayName