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
lima
::
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.
-
CtAccumulation *
accumulation
()¶ Returns a pointer to the accumulation control.
-
CtVideo *
video
()¶ Returns a pointer to the video control.
-
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 Callback¶
-
struct
ImageStatus
¶
-
class
ImageStatusCallback
¶
-
class
ImageStatusThread
: public Thread¶
-
class
SoftOpErrorHandler
: public EventCallback¶
-
struct
Status
¶
-
CtAcquisition *
Acquisition Interface¶
Saving Interface¶
-
class
lima
::
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 idheader
: 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>&, 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 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 saveaNbFrames
: 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
- Parameters
pars
: parameters for the saving streamstream_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 parametersstream_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 Callback¶
-
class
_SavingErrorHandler
: public EventCallback¶
-
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
-
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
-
struct
Stat
¶
-
bool
-
void
Image Interface¶
-
class
CtImage
¶ Control image processing settings such as ROI, binning and rotation.
Shutter Interface¶
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.
-
enumerator
-
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
¶
-
enumerator
Camera Plugin API¶
Hardware Interface¶
The Hardware Interface is the low level interface that must be implemented by detector plugins.
-
class
lima
::
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
-
void
getCapList
(CapList&) const = 0¶ Returns a list of capabilities.
-
void
reset
(ResetLevel reset_level) = 0¶ Reset the hardware interface.
-
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.
-
void
startAcq
() = 0¶ Start the acquisition.
-
void
stopAcq
() = 0¶ Stop the acquisition.
-
void
getStatus
(StatusType &status) = 0¶ Returns the current state of the hardware.
-
int
getNbAcquiredFrames
()¶ Returns the number of acquired frames.
-
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.
-
enumerator
-
enum
-
typedef struct lima::HwInterface::Status
Capabilities interfaces¶
-
class
lima
::
HwDetInfoCtrlObj
¶ Provides static information about the detector and the current image dimension.
Public Functions
-
void
getMaxImageSize
(Size &max_image_size) = 0¶ Return the maximum size of the image.
-
void
getDetectorImageSize
(Size &det_image_size) = 0¶ Return the size of the detector image, it is always equal or greater than the MaxImageSize.
-
void
getDefImageType
(ImageType &def_image_type) = 0¶ Returns the default data type of image (ushort, ulong, …)
-
void
getCurrImageType
(ImageType &curr_image_type) = 0¶ Returns the current data type of image (ushort, ulong, …).
-
void
getPixelSize
(double &x_size, double &y_size) = 0¶ Physical size of pixels (in mm)
-
void
getDetectorType
(std::string &det_type) = 0¶ Returns the type of the detector (Frelon, Maxipix, …)
-
void
getDetectorModel
(std::string &det_model) = 0¶ Returns the model of the detector.
-
void
registerMaxImageSizeCallback
(HwMaxImageSizeCallback &cb) = 0¶ Register a callback called when the detector is reconfigured with a different geometry.
-
void
unregisterMaxImageSizeCallback
(HwMaxImageSizeCallback &cb) = 0¶ Unregister a callback previsouly registered with registerMaxImageSizeCallback.
-
void
setUserDetectorName
(const std::string &username)¶ Set a detector user name.
-
void
getUserDetectorName
(std::string &username)¶ Get a detector user name.
-
void
-
class
lima
::
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
-
void *
getBufferPtr
(int buffer_nb, int concat_frame_nb = 0) = 0¶ Returns a pointer to the buffer at the specified location.
-
void *
getFramePtr
(int acq_frame_nb) = 0¶ Returns a pointer to the frame at the specified location.
-
void
getStartTimestamp
(Timestamp &start_ts) = 0¶ Returns the start timestamp.
-
void
getFrameInfo
(int acq_frame_nb, HwFrameInfoType &info) = 0¶ Returns some information for the specified frame number such as timestamp.
-
class
Callback
¶
-
class
lima
::
HwSyncCtrlObj
¶ Public Functions
-
bool
checkTrigMode
(TrigMode trig_mode) = 0¶ Check wether a given trigger mode is supported.
-
void
setTrigMode
(TrigMode trig_mode) = 0¶ Set the triggering mode.
-
void
getTrigMode
(TrigMode &trig_mode) = 0¶ Get the current triggering mode.
-
void
setExpTime
(double exp_time) = 0¶ Set the frame exposure time.
-
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
-
void
setLatTime
(double lat_time) = 0¶ Set the latency time between frames.
-
void
getLatTime
(double &lat_time) = 0¶ Get the current latency time between frames.
-
class
ValidRangesCallback
¶
-
struct
ValidRangesType
¶
-
bool
Implementations Helpers¶
-
class
lima
::
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.
-
class
Sync
: public Callback¶
-
void *