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

virtual bool needCompressionTask(Data&)

should return true if a compression task is needed for data, or false if blocks are found in sidebandData.

must call has/useCompressedSidebandData helpers

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

get a new compression task at each call.

this method is not call if needParallelCompression return false

inline virtual int getCompressedBufferSize(int data_size, int data_depth)

get the required ZBuffer size for compression.

struct Stat
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.

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