norama direct_v0.2

Overview

The norama-direct software allows to perform gnomonic projections to extract rectilinear images from equirectangular mappings or tiles of equirectangular mappings. This software is an interface to the projection algorithms offered by libgnomonic.

According to parameters and swicthes, the software can extract rectilinear images from tiles or entire mappings using different way to specifying the projection parameters, each corresponding to a simplification of the generic algorithm parameters specification.

Usage

The norama-direct software expects the following switches, arguments and parameters. Starting with the execution switches :

--generic -N

This swicth indicates that the libgnomonic generic projection has
to be used. It follows that an equirectangular tile is waited as input.
If this switch is given, the following parameters have to be given : 

    --rect-width, --rect-height (or --seed), --map-width, --map-height,
    --sight-x, --sight-y, --tile-x, --tile-y, --azimuth, --elevation, 
    --roll, --focal, --pixel

in order to perform the projection.

--elphel -E

This switch indicates that the libgnomonic Elphel-specific projection
has to be used. It follows that an equirectangular tile is waited
as input. If this switch is given, the following parameters have to
be given : 

    --rect-width, --rect-height (or --seed), --map-width, --map-height,
    --sight-x, --sight-y, --tile-x, --tile-y, --azimuth, --heading,
    --elevation, --roll, --focal, --pixel

in order to perform the projection.

--center -T

This switch indicates that the libgnomonic center-specific projection
has to be used. It follows that an equirectangular tile is waited
as input. If this switch is given, the following parameters have to
be given : 

    --rect-width, --rect-height (or --seed), --map-width, --map-height,
    --tile-x, --tile-y, --azimuth, --elevation, --roll, --focal,
    --pixel

in order to perform the projection.

--complete -P

This switch indicates that the libgnomonic apperture-specific
projection has to be used. It follows that an entire equirectangular
mappign is waited as input. If this switch is given, the following
parameters have to be given : 

    --rect-width, --rect-height (or --seed), --azimuth, --elevation, 
    --roll, --apperture

in order to perform the projection.

--force-rgb -F

This switch force the input image to be interpreted as a three
chromatic layers image. It means that even a transparency channel
is provided with the input image, it will not be used.

--clear -C

This switch indicates that the output buffer has to be initialized
befor projection. If a seed image is provided, it is then erased.
The clear color is set using : 

    --red, --green, --blue

parameters.

The stream arguments and parameters are :

--input -i

Path of the input equirectangular image, tile or entire mapping.

--output -o

Path of the output rectilinear image.

--seed -s

Path of the rectilinear image to use as seed of the output image.
This allows to initialize the rectilinear image in case the input
image provides an alpha channel.

--rect-width -k, --rect-height -l

Size, in pixels, of the output rectilinear image to create. If a seed is
specified, those parameters are ignored.

--map-width -W, --map-height -H

When an equirectangular tile is considered as input, the size, in pixels,
of the entire mapping from which it comes from has to be given through
those parameters.

--tile-x -X, --tile-y -Y

When an equirectangular tile is considered as input, the position, in
pixels, of the top-left corner of the tile in the entire mapping has to
be given through those parameters.

Considering the projection arguments and parameters :

--apperture -u

Apperture angle, in degrees, of the projection. This parameter is
only considered by the apperture-specific algorithm.

--sight-x -x, --sight-y -y

Position on rectilinear image, in floating pixels, of the center of the
gnomonic projection.

--azimuth -a, --heading -d, --elevation -e, --roll -r

Angular positions, in degrees, of the gnomonic projection center
according to the mapped sphere. The heading angle has to be 
considered as an azimuth angle correction and it is only considered 
by the Elphel-specific projection.

--focal -f

Focal length of the recilinear image, view as a virtual camera sensor,
given in millimeters.

--pixel -p

Pixel size of the rectilinear image, view as a virtual camera sensor,
given in millimeter and assumed to be identical in both directions.

The interpolation method arguments and parameters are :

--interpolation -n

Interpolation method to use for output image computation. The possible
methods are : 

    bilinearf | bicubicf | bipenticf | bihepticf

given in growing complexity order.

The parallelization arguments and parameters are :

--threads -t

This parameter is used to override the default thread count for
performence improvement.

Finally, the help switch is :

--help -h

Display minimal usage summary.

Demonstration

As demonstration, we consider the apperture-specific projection algorithm throught the following equirectangular mapping (copyright (c) Didier Mouron under CC BY-SA license) captured using an Eyesis4Pi camera :

Considering an azmiuth angle of 90 degrees, a elevation angle of 22 degrees, a roll angle of 11 degrees and an apperture parameter of 90 degrees, the follwing rectilinear image is extracted :

A fast bipentic interpolation was considered to generates the previous image. The other projection algorithms work the same except that a correlation is introduced between gnomonic center angular position and the position (and the size) of the tile in the entire mapping from which it is extracted.

Compilation

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

$ make clean && make

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

$ make documentation

When documentation is generated, the previous one is preliminary removed.