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 Callback¶
-
struct ImageStatus¶
-
class ImageStatusCallback¶
Subclassed by lima::CtTestApp::ImageStatusCallback
-
class ImageStatusThread : public Thread¶
-
class SoftOpErrorHandler : public EventCallback¶
-
struct Status¶
-
inline CtAcquisition *acquisition()¶
Acquisition 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>&, 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
- 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&, 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 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
-
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
-
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 havy task to do before saving if return is true, getCompressionTask should return a Task
See also
-
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¶
-
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 Callback¶
-
virtual void *getBufferPtr(int buffer_nb, int concat_frame_nb = 0)¶