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

inline CtAcquisition *acquisition(): Returns a pointer to the acquisition control.

inline CtSaving *saving(): Returns a pointer to the saving control.

inline CtImage *image(): Returns a pointer to the image control.

inline CtBuffer *buffer(): Returns a pointer to the buffer control.

inline CtAccumulation *accumulation(): Returns a pointer to the accumulation control.

inline CtVideo *video(): Returns a pointer to the video control.

inline CtShutter *shutter(): Returns a pointer to the shutter control.

inline CtEvent *event(): Returns a pointer to the event control.

Public Functions

void abortAcq(): stop an acquisition and purge all pending tasks.

void stopAcqAsync(AcqStatus acq_status, ErrorCode error_code, Data &data)

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

Creates a dummy task that calls stopAcq() and waits for all buffers to be released

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

This function is DEPRECATED.

Use stopAcqAsync instead

void registerImageStatusCallback(ImageStatusCallback &cb): registerImageStatusCallback is not thread safe!!!

void unregisterImageStatusCallback(ImageStatusCallback &cb): unregisterImageStatusCallback is not thread safe!!!

class _AbortAcqCallback : public TaskEventCallback

class _LastBaseImageReadyCallback : public TaskEventCallback

class _LastCounterReadyCallback : public TaskEventCallback

class _LastImageReadyCallback : public TaskEventCallback

class _LastImageSavedCallback : public TaskEventCallback

class _ReconstructionChangeCallback : public HwReconstructionCtrlObj::Callback

struct ImageStatus

class ImageStatusCallback: Subclassed by lima::CtTestApp::ImageStatusCallback

class ImageStatusThread : public Thread

class SoftOpErrorHandler : public TaskMgr::EventCallback

struct Status

Acquisition Interface

class CtAcquisition

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

class _ValidRangesCallback : public HwSyncCtrlObj::ValidRangesCallback 

struct Parameters

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 setUseHwComp(bool active, int stream_idx = 0): set the useHwComp active flag for a saving stream

void getUseHwComp(bool &active, int stream_idx = 0) const: get the useHwComp active flag 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 setZBufferParameters(const BufferHelper::Parameters &pars, int stream_idx = 0)

}

set zbuffer parameters for a saving stream

@param pars zbuffer parameters for the saving stream
@param stream_idx the id of the saving stream

void getZBufferParameters(BufferHelper::Parameters &pars, int stream_idx = 0)

get the zbuffer stream parameters

@param pars the return zbuffer parameters
@param stream_idx the stream id

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.

@param frame_nr the frame id
@param 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

@param frame_nr the frame id

void removeAllFrameHeaders(): remove all frame header

void getStatistic(std::list<double>&, std::list<double>&, std::list<double>&, std::list<double>&, 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 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

@param aFrameNumber the frame id you want to save
@param 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&, int stream_idx = 0) const: get the maximum number of parallel writing tasks

void setMaxConcurrentWritingTask(int, 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

@param pars parameters for the saving stream
@param stream_idx the id of the saving stream

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

get the saving stream parameters

@param pars the return parameters
@param 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

class _NewFrameSaveCBK : public HwSavingCtrlObj::Callback

class _SavingErrorHandler : public TaskMgr::EventCallback

struct _SavingSidebandData : public sideband::Data

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 the saving reacts it find existing filename

bool useHwComp: use HW (sideband) compression

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

inline virtual bool needParallelCompression() const

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

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.

struct Parameters

Buffer Interface

class CtBuffer

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

class _DataBuffer : public MappedBuffer

Statuses

enum lima::AcqStatus

The global acquisition status.

Values:

enumerator AcqReady: Acquisition is Ready.

enumerator AcqRunning: Acquisition is Running.

enumerator AcqFault: An error occured.

enumerator AcqConfig: Configuring the camera.

enum lima::DetStatus

Compound bit flags specifying the current detector status.

Values:

enumerator DetIdle

enumerator DetFault

enumerator DetWaitForTrigger

enumerator DetShutterOpen

enumerator DetExposure

enumerator DetShutterClose

enumerator DetChargeShift

enumerator DetReadout

enumerator DetLatency

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.

virtual 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:

enumerator Fault: Fault.

enumerator Ready: Ready for acquisition.

enumerator Exposure: Counting photons.

enumerator Readout: Reading data from the chip.

enumerator Latency: Latency between exposures.

enumerator 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 meter)

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.

inline virtual void setUserDetectorName(const std::string &username): Set a detector user name.

inline 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.

virtual bool checkAutoExposureMode(AutoExposureMode mode) const: Check wether a given auto exposure mode is supported.

virtual 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.

class ValidRangesCallback

struct ValidRangesType

Callbacks

class HwFrameCallback: Subclassed by lima::HwTestApp::FrameCallback

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

virtual void *getBufferPtr(int buffer_nb, int concat_frame_nb = 0): Returns a pointer to the buffer at the specified location.

virtual void *getFramePtr(int acq_frame_nb): Returns a pointer to the frame at the specified location.

virtual void getStartTimestamp(Timestamp &start_ts): Returns the start timestamp.

virtual void getFrameInfo(int acq_frame_nb, HwFrameInfoType &info): Returns some information for the specified frame number such as timestamp.

class Sync : public lima::HwBufferCtrlObj::Callback 