__attribute__ Struct Reference

Keyword The IMAGE_KEYWORD structure includes : More...

#include <ImageStruct.h>

Data Fields

char name [16]
 Image Name. More...
char type
union {
   int64_t   numl
   double   numf
   char   valstr [16]
char comment [80]
uint8_t xpix
uint8_t ypix
uint16_t dtus
 Detection time since beginning of "exposure" [us]. More...
uint8_t lambda_index
uint8_t naxis
 Number of axis. More...
uint32_t size [3]
 Image size along each axis. More...
uint64_t nelement
 Number of elements in image. More...
uint8_t atype
 Data type. More...
double creation_time
double last_access
union {
   struct timespec   ts
   TIMESPECFIXED   tsfixed
 Acquisition time (beginning of exposure. More...
uint8_t shared
uint8_t status
uint8_t logflag
uint16_t sem
uint64_t __pad0__: 0
uint64_t cnt0
uint64_t cnt1
uint64_t cnt2
uint8_t write
uint16_t NBkw
uint8_t used
 Image usage flag. More...
int32_t shmfd
uint64_t memsize
sem_t * semlog
union {
   uint8_t *   UI8
   int8_t *   SI8
   uint16_t *   UI16
   int16_t *   SI16
   uint32_t *   UI32
   int32_t *   SI32
   uint64_t *   UI64
   int64_t *   SI64
   float *   F
   double *   D
   complex_float *   CF
   complex_double *   CD
   EVENT_UI8_UI8_UI16_UI8 *   event1121
 data storage array More...
sem_t ** semptr

Detailed Description

Keyword The IMAGE_KEYWORD structure includes :

IMAGE structure The IMAGE structure includes :

Image metadata.

Photon detection events.

  • name
  • type
  • value

Log individual photon events on a 2D camera
Timing resolution = 1 us
Optimized for small size
Max detector size 256 x 256 pix
Max "exposure" time is 2^16 us = 65.535 ms (15.28 Hz)
Wavelength resolution set by keywords in frame:
lambda = LAMBDA_MIN + (LAMBDA_MAX-LAMBDA_MIN)/256*lambda_index
USAGE: An array of EVENT_UI8_UI8_UI16_UI8 is stored in the IMAGE structure
The array can be 1D (list of events), or 3D (N x 1 x M) for a circular buffer where the z-index (slice) is incremented between each "exposure"
md[0].cnt2 contains the number of events in the last slice written
Detection events do not have to be ordered
Write sequence in circular buffer :

  • [1] create IMAGE structure type EVENT_UI8_UI8_UI16_UI8. Size n x 1 x m, where n = max # of event per "exposure", m = number of slices in circular buffer. Note that md[0].size[0]=m, md[0].size[1]=1, md[0].size[2]=m
  • [2] set md[0].write=1 (start image write)
  • [3] set k=md[0].cnt1=0 (slice index)
  • [4] set md[0].cnt2=0 (# of events), ii=0 (event index in current slice)
  • [5] store time in local variable (exposure start)
  • [6] Write each event in array.EVENT_UI8_UI8_UI16_UI8[k*md[0].size[0]+ii]. After each event, increment ii (event index)
  • [7] When "exposure" completed, set md[0].atime to exposure time start (see step [5]), md[0].cnt1=k (last slice written), md[0].cnt2=ii (number of events), set md[0].write=0 (write completed), increment md[0].cnt0, and post all semaphores
  • [8] Increment k (if k=md[0].size[2], set k=0), return to step [4]
Array size will define the maximum number of events packed in IMAGE. User is responsible for pushing out IMAGE and starting a new IMAGE or slice when max number of events is reached.

This structure has a fixed size regardless of implementation

size = 171 byte = 1368 bit
  • an array of IMAGE_KEWORD structures
  • an array of IMAGE_METADATA structures (usually only 1 element)
size = 136 byte = 1088 bit

Field Documentation

uint64_t __attribute__::__pad0__
union { ... } __attribute__::array

data storage array

The array is declared as a union, so that multiple data types can be supported
For 2D image with pixel indices ii (x-axis) and jj (y-axis), the pixel values are stored as array.<TYPE>[ jj * md[0].size[0] + ii ]
image md[0].size[0] is x-axis size, md[0].size[1] is y-axis size

For 3D image with pixel indices ii (x-axis), jj (y-axis) and kk (z-axis), the pixel values are stored as array.<TYPE>[ kk * md[0].size[1] * md[0].size[0] + jj * md[0].size[0] + ii ]
image md[0].size[0] is x-axis size, md[0].size[1] is y-axis size, md[0].size[2] is z-axis size

Up to this point, all members of the structure have a fixed memory offset to the start pointpointer to data array
union { ... } __attribute__::atime

Acquisition time (beginning of exposure.

atime is defined as a union to ensure fixed 16-byte length regardless of struct timespec implementation

Data Type: struct timespec The struct timespec structure represents an elapsed time. It is declared in time.h and has the following members: time_t tv_sec This represents the number of whole seconds of elapsed time. long int tv_nsec This is the rest of the elapsed time (a fraction of a second), represented as the number of nanoseconds. It is always less than one billion.

On (most ?) 64-bit systems: sizeof(struct timespec) = 16 : sizeof(long int) = 8; sizeof(time_t) = 8

sizeof(struct timespec) is implementation-specific, and could be smaller that 16 byte. Users may need to create and manage their own timespec implementation if data needs to be portable across machines.
uint8_t __attribute__::atype

Data type.

Encoded according to data type defines.

  • 1: uint8_t
    • 2: int8_t
    • 3: uint16_t
    • 4: int16_t
    • 5: uint32_t
    • 6: int32_t
    • 7: uint64_t
    • 8: int64_t
    • 9: IEEE 754 single-precision binary floating-point format: binary32
  • 10: IEEE 754 double-precision binary floating-point format: binary64
  • 11: complex_float
  • 12: complex double
complex_double* __attribute__::CD
complex_float* __attribute__::CF
uint64_t __attribute__::cnt0

counter (incremented if image is updated)

uint64_t __attribute__::cnt1

in 3D rolling buffer image, this is the last slice written

uint64_t __attribute__::cnt2

in event mode, this is the # of events

char __attribute__::comment[80]
double __attribute__::creation_time

creation time (since process start)

double* __attribute__::D
uint16_t __attribute__::dtus

Detection time since beginning of "exposure" [us].

Beginning of exposure is written to md[0].atime

EVENT_UI8_UI8_UI16_UI8* __attribute__::event1121
float* __attribute__::F
IMAGE_KEYWORD* __attribute__::kw
uint8_t __attribute__::lambda_index
double __attribute__::last_access

last time the image was accessed (since process start)

uint8_t __attribute__::logflag

set to 1 to start logging

IMAGE_METADATA* __attribute__::md
uint64_t __attribute__::memsize

total size in memory if shared

char __attribute__::name

Image Name.

keyword name

local name (can be different from name in shared memory)

uint8_t __attribute__::naxis

Number of axis.

1, 2 or 3. Values above 3 not allowed.
uint16_t __attribute__::NBkw

number of keywords (max: 65536)

uint64_t __attribute__::nelement

Number of elements in image.

This is computed upon image creation

double __attribute__::numf
int64_t __attribute__::numl
uint16_t __attribute__::sem

number of semaphores in use, specified at image creation

sem_t* __attribute__::semlog

pointer to semaphore for logging (8 bytes on 64-bit system)

sem_t** __attribute__::semptr

array of pointers to semaphores (each 8 bytes on 64-bit system)

uint8_t __attribute__::shared

1 if in shared memory

int32_t __attribute__::shmfd

if shared memory, file descriptor

int16_t* __attribute__::SI16
int32_t* __attribute__::SI32
int64_t* __attribute__::SI64
int8_t* __attribute__::SI8
uint32_t __attribute__::size[3]

Image size along each axis.

If naxis = 1 (1D image), size[1] and size[2] are irrelevant

uint8_t __attribute__::status

1 to log image (default); 0 : do not log: 2 : stop log (then goes back to 2)

struct timespec __attribute__::ts
TIMESPECFIXED __attribute__::tsfixed
char __attribute__::type

N: unused, L: long, D: double, S: 16-char string

uint16_t* __attribute__::UI16
uint32_t* __attribute__::UI32
uint64_t* __attribute__::UI64
uint8_t* __attribute__::UI8
uint8_t __attribute__::used

Image usage flag.

1 if image is used, 0 otherwise.
This flag is used when an array of IMAGE type is held in memory as a way to store multiple images.
When an image is freed, the corresponding memory (in array) is freed and this flag set to zero.
The active images can be listed by looking for IMAGE[i].used==1 entries.

char __attribute__::valstr[16]
union { ... } __attribute__::value
uint8_t __attribute__::write

1 if image is being written

uint8_t __attribute__::xpix
uint8_t __attribute__::ypix

The documentation for this struct was generated from the following file: