csps export_v0.4.3

Overview

The csps-export software is used to convert data from processed CSPS structure into JSON file. The JSON file contains general information on considered CSPS processed structure and information about each camera capture such as position and orientation. It also initialize JSON fields that are modified by other softwares engage in camera raw data processing. In this way, the JSON file is the reference used for raw data management interface.

It is also designed to be able to consider a previous JSON file in order to update its content only considering the fields that are not modified by other softwares in order to update only CSPS related fields.

When CSPS data are not available, the csps-export is also able to create template JSON file, containing empty fields, that can then be used by the raw data processing chain software to stores their specific information.

Usage

The csps-export software expects the following arguments and parameters. Starting with the execution switches :

-template -l

If this execution switch is provided, the software creates a
template JSON file.

The stream arguments and parameters are :

--path -p

Path to the CSPS directory structure.

--export -e

Path to the exportation file. This path can point to the 
previously created JSON file to update its content.

The CSPS stream tags specification are performed through the following arguments and parameters :

--cam-tag -c, --cam-mod -m

CSPS-tag of the camera device and CSPS-module to consider for
query on CSPS, respectively.

--gps-tag -g, --gps-mod -n

CSPS-tag of the GPS device and CSPS-module to consider for query
on CSPS, respectively.

--imu-tag -i, --imu-mod -s

CSPS-tag of the IMU device and CSPS-module to consider for query
on CSPS, respectively.

--still-tag -t, --still-mod -k

CSPS-tag of still range device and CSPS-module to consider for
query on CSPS, respectively.

Missing GPS signal can be managed using the following argument and parameter :

--forced -f

Allow to manually specify all the camera captures position using
the parameter that contains the longitude, latitude and altitude
separated by comas.

Demonstration

Considering a CSPS-processed structure obtained using an eyesis4pi camera device in Geneva, the following JSON output is obtained using csps-export software :

{
    "split":false,
    "preview":false,
    "trash":false,
    "pose":
    [
    {
        "still":true,
        "raw":"unknown",
        "sec":1400683814,
        "usec":523612,
        "position":null,
        "orientation":
        [
            2.4026949016698651e-01,
            9.6618697580735757e-01,
            9.2787060633467353e-02,
            -9.6088073919725547e-01,
            2.5028126416312613e-01,
            -1.1799110044227233e-01,
            -1.3724648491518088e-01,
            -6.0798024117707308e-02,
            9.8866881868411360e-01,
            0.0000000000000000e+00 
        ]
    },
    ...
    ],
    "single":true,
    "gps":true
}

Fields are related to FOXEL storage structure and raw data management. General fields are available and are described here :

split : this field, related to Elphel manufacturer is used to
specify if raw files coming from the camera have been separated
in individual raw image files.

preview : this field indicates if captured image preview files
have been computed.

trash : this field indicates if raw image file integrity check
have been performed.

single : this field indicates if the GPS position of the images
have been forced manually.

gps : this field indicates if at least one raw image of the
sequence comes with a valid GPS position. If the field is set to
false, none of the image have a GPS position.

The rest of the file is occupied by the camera images array, the poses array, each element of this array giving the information for one particular pose. The fields of the array elements are described here :

still : this field indicates if the camera was immobile during
the acquisition of the pose.

raw : this field indicates the state of the pose raw image
file(s). If the field indicates 'unknown', the pose have not
been checked. If 'valid' is indicated, the pose image file(s)
is (are) valid. If 'trash' is given, the pose image file(s) is
(are) corrupted. If 'miss' is provided, the set of pose image
files is not complete, the pose being considered as invalid.

sec/usec : those fields provides the UNIX timestamps and the
microseconds, when available, describing the camera pose capture
time.

position : the position field gives the GPS position of the pose
according to WGS84 standard. The longitude, latitude and
altitude are given in this order. The last coordinates indicates
the reliability of the position according to the position 
interpolation procedure (low value are better).

orientation : this field gives the orientation matrix of the
pose according to local East-North-Up (ENU) frame. The last
component gives the orientation reliability according to the
orientation interpolation procedure (low value are better).

When position or orientation is set to null, it simply means that the information is missing for the considered pose.

Compilation

The software binary can be build using its specific makefile by simply typing in its base directory :

$ make clean && make build [OPENMP=false]

The binary is placed in the local bin directory and is not copied in the main bin directory. To generate the documentation, use the command :

$ make clean-documentation && make documentation

To install or uninstall the binaries on the local computer, use the commands :

# make install
# make uninstall