Building Blocks

Patch

A patch is a data and metadata container and represent the fundamental building block of Aliquis. A patch is optimized to be an image container, but it can store as data any multidimensional array. Any patch has a list of metadata with additional informations:

  • parent: indicate the high level patch from which the patch come from
  • values: an array of values, useful for classification purpose
  • transform: store the transformation matrix respect the parent patch
  • colorformat: the colorformat of the data image
  • values range: the range of the data values
  • shapes: containing a list of shapes

Informations in Aliquis are patches-driven: aliquis use metadata to build a workflow across stages and pipelines, the user doesn’t really care about them.

Stage

Stages are the elementary computational building blocks in Aliquis. A stage take one or more patches as input, elaborate them and produce a patch as output. A particular kind of stage can produce output patches without input patches: this is called source stage.

Aliquis comes with a large variety of stages, each one perform a particular operation on the input patches. The behaviour of each stage can be controlled modifying his parameters.

A stage has the following general structure:

stages {
  name: "stage_name"
  type: STAGE_TYPE
  input: "input_stage"
  stage_type_param {
    ...
  }
}

Each stage has a name, which identify it univocally, a type which defines the operation performed by the stage, an input from which the stage load the patches and a stage_type_param specific of each stage and which control the behaviour of it.

Pipeline

A pipeline is a directed acyclic graph whose nodes are stages. Pipeline must have at least one input stage which create the patches stream and can have an arbitrary number of output stage. An ouput stage in a pipeline is every stage whose ouput patches aren’t catched from another stage. In a pipeline the information go through stages in a stream of patches.

A pipeline has the following general syntax:

name: "pipeline_name"

stages { ... }
stages { ... }
     ...
stages { ... }

Also in a pipeline, a name identify univocally the pipeline, and a set of stages describe the task performed by the pipeline. A pipeline can be defined in a .apl file with any text editor.

Host

An host in Aliquis is every program which run a pipeline and eventually handle his output. Aliquis comes with different pre-build hosts which perform different tasks on pipeline’s ouput.

  • aliquispl_run: this is the simplest and principal host in Aliquis. It can show the output of a pipeline and perform other relatively simple visualization tasks. This host can be launched in a terminal, specifying the pipeline.apl and arguments in order to perform different operation:

    • --output OUTPUT: save the ouputs in the specified OUTPUT directory instead of show them on display
    • --force-display: show outputs on display even if –outputs is used
    • --show-input: display or save the input patches instead the output ones
    • --stages STAGES: Stage(s) to save/display
    • --decorate: decorate the pipeline outputs with the result of classification or segmentation
    • --class-file FILE: specify a file containing the class names, one per row, for decoration
    • --fps FPS: set the output video framerate. By default is 0, autodetection.
    • --show-fps: shows the framerate
    • --continuos-delay DELAY: show the output patches continuosly with a specified millisecond DELAY. By default is turned off and patches can be shown one by one using arrow keys
  • aliquispl_lmdb: through this host we can create an lmdb from the outputs of a pipeline. This can be done running aliquispl_lmdb create with the pipeline apl and the output path of the lmdb. Optional arguments can be specified to achieve different results:

    • -a: append the output to an existing lmdb
    • -s SIZE: crop the patches in SIZE patches
    • -f: wheter to use native float32 format
    • -c: qheter to compress the lmdb values
    • -i IMGSFILE: load the images from a file containing a list of images path and eventually an associated class number (label). In this case you must use a NULL pipeline to do it correctly (see example)
    • --save PATH: save the output patches

    aliquispl_lmdb comes with extra tools for lmdb manipulation which doesn’t handle a pipeline and can’t be define properly as hosts:

    • aliquispl_lmdb export: export the lmdb to files
    • aliquispl_lmdb compare: compare two lmdb database
    • aliquispl_lmdb concat: concatenate two or more lmdb
    • aliquispl_lmdb subset: extract a subset lmdb from a larger one
    • aliquispl_run relabel: change the labels in an existing lmdb
    • aliquispl_run view: show the images in the lmdb
    • aliquispl_run info: show lmdb informations
    • aliquispl_run pca: compute the principal component analysis on lmdb
    • aliquispl_run stats: compute statistical values on *lmdb

    You can show advanced options to use every tool running each one with the argument --help.

  • aliquispl_caffe: this host allow to train a Caffe neural network with the output patches of a pipeline. This can be useful, for example, to do a data augmentation without the creation of a new database. The host can be used running aliquispl_caffe with the pipeline apl and the solver prototxt. Additionally a caffemodel with pretrained weights for finetuning can be specified.

    Also aliquispl_caffe has extra tool useful for Caffe:

    • aliquispl_caffe mean: compute a mean of an existing lmdb and generate the corresponding .binaryproto file
    • aliquispl_caffe compare: compare two different caffe models

Aliquisd