Queries example_v1.2

Overview

This page gives an example of usage of libfastcal for calibration data access. In order to perform queries on data, the library has to load the key/value-file that contains the calibration data. The library builds the key/value-file descriptor that is required by the query methods. When queries are done, the library provides a function to release the descriptor.

Demonstration

One considers an Elphel camera device with MAC address AA:BB:CC:DD:EE:FF and a standard storage structure mounted on /data/. The following C code shows how to create the key/value-file descriptor and how to perform queries :

/* Key/value-file descriptor */
lf_Descriptor_t lfDesc;

/* Values that recieve queried calibration data */
lf_Size_t lfValue1 = 0;
lf_Real_t lfValue2 = 0.0;

/* Creation and verification of the descriptor */
if ( lf_parse( "AA-BB-CC-DD-EE-FF", "/data/", & lfDesc ) == LF_TRUE ) {

    /* Query number of camera modules */
    lfValue1 = lf_query_modules( & lfDesc );

    /* Query focal length of camera sensor 8 */
    lfValue2 = lf_query_focalLength( 8, & lfDesc );

    /* Release descriptor */
    lf_release( & lfDesc );

} else {

    /* Unable to access key/value-file */
    printf( "Unable to create descriptor\n" );

}

When queries are done, the descriptor release function is called to unallocate memory. If the descriptor release is not performed, memory leaks are expected.

Implemented methods

Depending on queried calibration data value, the method prototypes are slightly different. This section provides the list of implemented methods and their prototype. So as to better understand this section, the following library typedefs are remainded :

typedef unsigned char lf_Char_t;
typedef double        lf_Real_t;
typedef long int      lf_Size_t;

Camera string values

For query on string values, the method prototype is :

lf_Char_t * lf_query_[key]( lf_Descriptor_t * lfDesc );

and the available methods are :

lf_query_camera                Camera MAC address
lf_query_type                  Camera type
lf_query_model                 Camera model
lf_query_imu                   Camera IMU device model
lf_query_gps                   Camera GPS reciever model

As descriptor is released, pointers provided by those methods are invalid and should not be used anymore.

Camera integer values

In this case, the prototype is :

lf_Size_t lf_query_[key]( lf_Descriptor_t * lfDesc );

and the available methods are :

lf_query_modules               Camera modules count
lf_query_channels              Camera sensors count

Sensor floating point values

In this case, the methods expect the sensor index :

lf_Real_t lf_query_[key]( lf_Size_t lfChannel, lf_Descriptor_t * lfDesc );

and the methods list is :

lf_query_focalLength           Sensor lense focal length
lf_query_azimuth               Sight azimuth angle
lf_query_elevation             Sight elevation angle
lf_query_heading               Sight azimuth angle correction
lf_query_pixelSize             Pixel size
lf_query_px0                   Principal point on equirectangular tile
lf_query_py0                   Principal point on equirectangular tile
lf_query_roll                  Sight roll angle
lf_query_radius                Radius of lense center in camera frame
lf_query_height                Height of lense center in camera frame
lf_query_entrancePupilForward  Sensor distance to focal point

Sensor integer values

The prototype of these methods is simply :

lf_Size_t lf_query_[key]( lf_Size_t lfChannel, lf_Descriptor_t * lfDesc );

and the implemented methods are :

lf_query_ImageFullWidth        Equirectangular panorama width
lf_query_ImageFullLength       Equirectangular panorama height
lf_query_XPosition             Tile x-position in panorama
lf_query_YPosition             Tile y-position in panorama
lf_query_pixelCorrectionWidth  Sensor width
lf_query_pixelCorrectionHeight Sensor height
lf_query_hflip                 Boolean that indicates horizontal symetry
                               necessity to retrieve sensor image from 
                               raw data
lf_query_vflip                 Boolean that indicates vertical symetry
                               necessity to retrieve sensor image from 
                               raw data

In case of non-string values, as the descriptor is released, only values that have already been cached through a previous query can still be accessed.