C++ API

Unfortunately very limited documentation is available from the source but that should improve over time.

User API

In this section we cover the classes that defines the user interface.

Hello, Lima!

Let’s get started with a simple example of an image acquisition function using the simulator camera.

// A camera instance and its hardware interface
Simulator::Camera simu;
Simulator::Interface hw(simu);

// The control object
CtControl ct = CtControl(&hw);

// Get the saving control and set some properties
CtSaving *save = ct.saving();
save->setDirectory("./data");
save->setPrefix("test_");
save->setSuffix(".edf");
save->setNextNumber(100);
save->setFormat(CtSaving::EDF);
save->setSavingMode(CtSaving::AutoFrame);
save->setFramesPerFile(100);

// Set the binning or any other processing
Bin bin(2, 2);
CtImage *image = ct.image();
image->setBin(bin);

// Get the acquisition control and set some properties
CtAcquisition *acq = ct.acquisition();
acq->setAcqMode(Single);
acq->setAcqExpoTime(expo);
acq->setAcqNbFrames(nframe);

// Prepare acquisition (transfer properties to the camera)
ct.prepareAcq();

// Start acquisition
ct.startAcq();
std::cout << "SIMUTEST: acq started" << std::endl;

//
long frame = -1;
while (frame < (nframe - 1))
{
      using namespace std::chrono;

      high_resolution_clock::time_point begin = high_resolution_clock::now();

      usleep(100000);

      CtControl::ImageStatus img_status;
      ct.getImageStatus(img_status);

      high_resolution_clock::time_point end = high_resolution_clock::now();

      auto duration = duration_cast<microseconds>(end - begin).count();

      std::cout << "SIMUTEST: acq frame nr " << img_status.LastImageAcquired
              << " - saving frame nr " << img_status.LastImageSaved << std::endl;

      if (frame != img_status.LastImageAcquired) {
              unsigned int nb_frames = img_status.LastImageAcquired - frame;

              std::cout << "  " << duration << " usec for " << nb_frames << " frames\n";
              std::cout << "  " << 1e6 * nb_frames / duration << " fps" << std::endl;

              frame = img_status.LastImageAcquired;
      }
}
std::cout << "SIMUTEST: acq finished" << std::endl;

// Stop acquisition ( not really necessary since all frames where acquired)
ct.stopAcq();

std::cout << "SIMUTEST: acq stopped" << std::endl;

Control Interfaces

The control interface is the high level interface that controls an acquisition.

class CtControl

Main client class which should be instantiated by the users in their acquisition software.

Advanced control accessors

CtAcquisition *acquisition()

Returns a pointer to the acquisition control.

CtSaving *saving()

Returns a pointer to the saving control.

CtImage *image()

Returns a pointer to the image control.

CtBuffer *buffer()

Returns a pointer to the buffer control.

CtAccumulation *accumulation()

Returns a pointer to the accumulation control.

CtVideo *video()

Returns a pointer to the video control.

CtShutter *shutter()

Returns a pointer to the shutter control.

CtEvent *event()

Returns a pointer to the event control.

Public Functions

void abortAcq()

stop an acquisition and purge all pending tasks.

void abortAcq(AcqStatus acq_status, ErrorCode error_code, Data &data, bool ctrl_mutex_locked = false)

aborts an acquisiton from a callback thread: it’s safe to call from a HW thread.

Creates a dummy task that calls stopAcq()

void registerImageStatusCallback(ImageStatusCallback &cb)

registerImageStatusCallback is not thread safe!!!

void unregisterImageStatusCallback(ImageStatusCallback &cb)

unregisterImageStatusCallback is not thread safe!!!

Acquisition Interface

class CtAcquisition

This class control the acquisition of images given a hardware interface.

Saving Interface

class CtSaving

Control saving settings such as file format and mode.

Saving modes

{

void setSavingMode(SavingMode mode)

set the saving mode for a saving stream

void getSavingMode(SavingMode &mode) const

get the saving mode for a saving stream

void setOverwritePolicy(OverwritePolicy policy, int stream_idx = 0)

set the overwrite policy for a saving stream

void getOverwritePolicy(OverwritePolicy &policy, int stream_idx = 0) const

get the overwrite policy for a saving stream

void setFramesPerFile(unsigned long frames_per_file, int stream_idx = 0)

set the number of frame saved per file for a saving stream

void getFramesPerFile(unsigned long &frames_per_file, int stream_idx = 0) const

get the number of frame saved per file for a saving stream

void setManagedMode(ManagedMode mode)

set who will manage the saving.

with this methode you can choose who will do the saving

  • if mode is set to Software, the saving will be managed by Lima core
  • if mode is set to Hardware then it’s the sdk or the hardware of the camera that will manage the saving.
    Parameters
    • mode: can be either Software or Hardware

void resetCommonHeader()

}

clear the common header

void setCommonHeader(const HeaderMap &header)

set the common header.

This is the header which will be write for all frame for this acquisition

void updateCommonHeader(const HeaderMap &header)

replace/add field in the common header

void getCommonHeader(HeaderMap &header) const

get the current common header

void addToCommonHeader(const HeaderValue &value)

add/replace a header value in the current common header

void updateFrameHeader(long frame_nr, const HeaderMap &header)

add/replace several value in the current frame header

void addToFrameHeader(long frame_nr, const HeaderValue &value)

add/replace a header value in the current frame header

void validateFrameHeader(long frame_nr)

validate a header for a frame.

this mean that the header is ready and can now be save. If you are in AutoHeader this will trigger the saving if the data frame is available

void getFrameHeader(long frame_nr, HeaderMap &header) const

get the frame header.

Parameters
  • frame_nr: the frame id
  • header: the current frame header

void takeFrameHeader(long frame_nr, HeaderMap &header)

get the frame header and remove it from the container

void removeFrameHeader(long frame_nr)

remove a frame header

Parameters
  • frame_nr: the frame id

void removeAllFrameHeaders()

remove all frame header

void getStatistic(std::list<double> &saving_speed, std::list<double> &compression_speed, std::list<double> &compression_ratio, std::list<double> &incoming_speed, int stream_idx = 0) const

get write statistic

void setStatisticHistorySize(int aSize, int stream_idx = 0)

set the size of the write time static list

int getStatisticHistorySize(int stream_idx = 0) const

get the size of the write time static list

void clear()

clear everything.

  • all header
  • all waiting data to be saved
  • close all stream

void writeFrame(int frame_nr = -1, int nb_frames = 1, bool synchronous = true)

write manually a frame

Parameters
  • aFrameNumber: the frame id you want to save
  • aNbFrames: the number of frames you want to concatenate

void setStreamActive(int stream_idx, bool active)

activate/desactivate a stream

void getStreamActive(int stream_idx, bool &active) const

get if stream is active

void getMaxConcurrentWritingTask(int &nb_threads, int stream_idx = 0) const

get the maximum number of parallel writing tasks

void setMaxConcurrentWritingTask(int nb_threads, int stream_idx = 0)

get the maximum number of parallel writing tasks

Public Functions

void setParameters(const Parameters &pars, int stream_idx = 0)

set saving parameter for a saving stream

Parameters
  • pars: parameters for the saving stream
  • stream_idx: the id of the saving stream

void getParameters(Parameters &pars, int stream_idx = 0) const

get the saving stream parameters

Parameters
  • pars: the return parameters
  • stream_idx: the stream id

void setDirectory(const std::string &directory, int stream_idx = 0)

set the saving directory for a saving stream

void getDirectory(std::string &directory, int stream_idx = 0) const

get the saving directory for a saving stream

void setPrefix(const std::string &prefix, int stream_idx = 0)

set the filename prefix for a saving stream

void getPrefix(std::string &prefix, int stream_idx = 0) const

get the filename prefix for a saving stream

void setSuffix(const std::string &suffix, int stream_idx = 0)

set the filename suffix for a saving stream

void getSuffix(std::string &suffix, int stream_idx = 0) const

get the filename suffix for a saving stream

void setOptions(const std::string &options, int stream_idx = 0)

set the additional options for a saving stream

void getOptions(std::string &options, int stream_idx = 0) const

get the additional options for a saving stream

void setNextNumber(long number, int stream_idx = 0)

set the next number for the filename for a saving stream

void getNextNumber(long &number, int stream_idx = 0) const

get the next number for the filename for a saving stream

void setFormat(FileFormat format, int stream_idx = 0)

set the saving format for a saving stream

void getFormat(FileFormat &format, int stream_idx = 0) const

get the saving format for a saving stream

void setFormatAsString(const std::string &format, int stream_idx = 0)

set the saving format as string for a saving stream

void getFormatAsString(std::string &format, int stream_idx = 0) const

get the saving format as string for a saving stream

void getFormatList(std::list<FileFormat> &format_list) const

get supported format list

void getFormatListAsString(std::list<std::string> &format_list) const

get supported format list as string

void setFormatSuffix(int stream_idx = 0)

force saving suffix to be the default format extension

void getHardwareFormatList(std::list<std::string> &format_list) const

return a list of hardware possible saving format

class _ManualBackgroundSaveTask : public SinkTaskBase

manual background saving

struct Parameters

Public Functions

Parameters()

Parameters default constructor.

Public Members

std::string directory

base path where the files will be saved

std::string prefix

prefix of the filename

std::string suffix

suffix of the filename

long nextNumber

next file number

FileFormat fileFormat

the saving format (EDF,CBF…)

SavingMode savingMode

saving mode (automatic,manual…)

OverwritePolicy overwritePolicy

how you the saving react it find existing filename

std::string indexFormat

ie: %.4d if you want 4 digits

long framesPerFile

the number of images save in one files

class SaveContainer

Subclassed by lima::SaveContainerCbf, lima::SaveContainerEdf, lima::SaveContainerFits, lima::SaveContainerHdf5, lima::SaveContainerNxs, lima::SaveContainerTiff

Public Functions

virtual bool needParallelCompression() const

should return true if container has compression or havy task to do before saving if return is true, getCompressionTask should return a Task

See
getCompressionTask

virtual SinkTaskBase *getCompressionTask(const CtSaving::HeaderMap&)

get a new compression task at each call.

this method is not call if needParallelCompression return false

See
needParallelCompression

class Stream
class _CompressionCBK : public TaskEventCallback

compression callback

class _SaveCBK : public TaskEventCallback

save callback

class _SaveTask : public SinkTaskBase

save task class

Image Interface

class CtImage

Control image processing settings such as ROI, binning and rotation.

Shutter Interface

class CtShutter

Control shutter settings such as open and close time.

Buffer Interface

class CtBuffer

Controls buffer settings such as number of buffers, binning and rotation.

Statuses

enum lima::AcqStatus

The global acquisition status.

Values:

AcqReady

Acquisition is Ready.

AcqRunning

Acquisition is Running.

AcqFault

An error occured.

AcqConfig

Configuring the camera.

enum lima::DetStatus

Compound bit flags specifying the current detector status.

Values:

DetIdle = 0x00
DetFault = 0x01
DetWaitForTrigger = 0x02
DetShutterOpen = 0x04
DetShutterClose = 0x10
DetChargeShift = 0x20
DetReadout = 0x40

Camera Plugin API

Hardware Interface

The Hardware Interface is the low level interface that must be implemented by detector plugins.

class HwInterface

As an interface to the Control Layer, this class exports the capabilities provided by the hardware.

It is implemented by every camera plugins.

Public Types

typedef struct lima::HwInterface::Status StatusType

A tuple of status with acquisition and detector status / mask.

Public Functions

virtual void getCapList(CapList&) const = 0

Returns a list of capabilities.

virtual void reset(ResetLevel reset_level) = 0

Reset the hardware interface.

virtual void prepareAcq() = 0

Prepare the acquisition and make sure the camera is properly configured.

This member function is always called before the acquisition is started.

virtual void startAcq() = 0

Start the acquisition.

virtual void stopAcq() = 0

Stop the acquisition.

virtual void getStatus(StatusType &status) = 0

Returns the current state of the hardware.

int getNbAcquiredFrames()

Returns the number of acquired frames.

virtual int getNbHwAcquiredFrames() = 0

Returns the number of acquired frames returned by the hardware (may differ from getNbAcquiredFrames if accumulation is on)

struct Status

A tuple of status with acquisition and detector status / mask.

Public Types

enum Basic

Basic detector states (some detectors may have additional states)

Values:

Fault

Fault.

Ready

Ready for acquisition.

Exposure

Counting photons.

Readout

Reading data from the chip.

Latency

Latency between exposures.

Config

Fault.

Public Members

AcqStatus acq

Global acquisition status.

DetStatus det

Compound bit flags specifying the current detector status.

DetStatus det_mask

A mask specifying the detector status bits that are supported by the hardware.

Capabilities interfaces

class HwDetInfoCtrlObj

Provides static information about the detector and the current image dimension.

Public Functions

virtual void getMaxImageSize(Size &max_image_size) = 0

Return the maximum size of the image.

virtual void getDetectorImageSize(Size &det_image_size) = 0

Return the size of the detector image, it is always equal or greater than the MaxImageSize.

virtual void getDefImageType(ImageType &def_image_type) = 0

Returns the default data type of image (ushort, ulong, …)

virtual void getCurrImageType(ImageType &curr_image_type) = 0

Returns the current data type of image (ushort, ulong, …).

virtual void getPixelSize(double &x_size, double &y_size) = 0

Physical size of pixels (in mm)

virtual void getDetectorType(std::string &det_type) = 0

Returns the type of the detector (Frelon, Maxipix, …)

virtual void getDetectorModel(std::string &det_model) = 0

Returns the model of the detector.

virtual void registerMaxImageSizeCallback(HwMaxImageSizeCallback &cb) = 0

Register a callback called when the detector is reconfigured with a different geometry.

virtual void unregisterMaxImageSizeCallback(HwMaxImageSizeCallback &cb) = 0

Unregister a callback previsouly registered with registerMaxImageSizeCallback.

virtual void setUserDetectorName(const std::string &username)

Set a detector user name.

virtual void getUserDetectorName(std::string &username)

Get a detector user name.

class HwBufferCtrlObj

This interface controls the image memory buffer allocation and management.

Buffers are used:

  • As temporary frame storage before saving, allowing disk / network speed fluctuations.
  • To permanently hold images that can be read by the user after the acquisition is finished. These buffer functionalities may be implemented by the hardware layer (kernel driver in the case of the Espia). If not, an auxiliary buffer manager class will be provided to facilitate (and unify) its software implementation. The buffer management parameters are :

Subclassed by lima::SoftBufferCtrlObj

Public Functions

virtual void *getBufferPtr(int buffer_nb, int concat_frame_nb = 0) = 0

Returns a pointer to the buffer at the specified location.

virtual void *getFramePtr(int acq_frame_nb) = 0

Returns a pointer to the frame at the specified location.

virtual void getStartTimestamp(Timestamp &start_ts) = 0

Returns the start timestamp.

virtual void getFrameInfo(int acq_frame_nb, HwFrameInfoType &info) = 0

Returns some information for the specified frame number such as timestamp.

class Callback

Subclassed by lima::SoftBufferCtrlObj::Sync

class HwSyncCtrlObj

Public Functions

virtual bool checkTrigMode(TrigMode trig_mode) = 0

Check wether a given trigger mode is supported.

virtual void setTrigMode(TrigMode trig_mode) = 0

Set the triggering mode.

virtual void getTrigMode(TrigMode &trig_mode) = 0

Get the current triggering mode.

virtual void setExpTime(double exp_time) = 0

Set the frame exposure time.

virtual void getExpTime(double &exp_time) = 0

Get the current frame exposure time.

bool checkAutoExposureMode(AutoExposureMode mode) const

Check wether a given auto exposure mode is supported.

void setHwAutoExposureMode(AutoExposureMode mode)

this method should be redefined in the subclass if the camera can managed auto exposure

virtual void setLatTime(double lat_time) = 0

Set the latency time between frames.

virtual void getLatTime(double &lat_time) = 0

Get the current latency time between frames.

Callbacks

class HwFrameCallback

Implementations Helpers

class SoftBufferCtrlObj : public lima::HwBufferCtrlObj

This class is a basic HwBufferCtrlObj software allocation implementation, It can be directly provided to the control layer as a HwBufferCtrlObj.

Public Functions

void *getBufferPtr(int buffer_nb, int concat_frame_nb = 0)

Returns a pointer to the buffer at the specified location.

void *getFramePtr(int acq_frame_nb)

Returns a pointer to the frame at the specified location.

void getStartTimestamp(Timestamp &start_ts)

Returns the start timestamp.

void getFrameInfo(int acq_frame_nb, HwFrameInfoType &info)

Returns some information for the specified frame number such as timestamp.