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 CtAccumulation *accumulation()
Returns a pointer to the accumulation control.
-
inline CtVideo *video()
Returns a pointer to the video 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
-
inline CtAcquisition *acquisition()
Acquisition Interface
-
class CtAcquisition
This class control the acquisition of images given a hardware interface.
-
class _ValidRangesCallback : public HwSyncCtrlObj::ValidRangesCallback
-
struct Parameters
-
class _ValidRangesCallback : public HwSyncCtrlObj::ValidRangesCallback
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
-
Parameters()
-
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
See also
-
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
See also
-
inline virtual SinkTaskBase *getCompressionTask(const CtSaving::HeaderMap&)
get a new compression task at each call.
this method is not call if needParallelCompression return false
See also
-
inline virtual int getCompressedBufferSize(int data_size, int data_depth)
get the required ZBuffer size for compression.
-
struct Stat
-
inline virtual bool needParallelCompression() const
-
void setSavingMode(SavingMode mode)
Image Interface
-
class CtImage
Control image processing settings such as ROI, binning and rotation.
Shutter Interface
Buffer 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 AcqReady
-
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 DetIdle
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.
-
enumerator Fault
-
enum Basic
-
typedef struct lima::HwInterface::Status StatusType
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.
-
virtual void getMaxImageSize(Size &max_image_size) = 0
-
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
-
virtual bool checkTrigMode(TrigMode trig_mode) = 0
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
-
virtual void *getBufferPtr(int buffer_nb, int concat_frame_nb = 0)