\input texinfo   @c -*-texinfo-*-
@setfilename gta.info
@documentlanguage en
@documentencoding UTF-8
@include version.texi
@settitle GTA Tool @value{VERSION}

@copying
This manual was last updated @value{UPDATED} for version
@value{VERSION} of GTA Tool.

Copyright (C) 2010, 2011, 2012, 2013, 2014
Martin Lambers @email{marlam@@marlam.de}

@quotation
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and this
notice are preserved. This file is offered as-is, without any warranty.
@end quotation
@end copying

@dircategory Individual utilities
@direntry
* Gtatool: (gta).                           Manipulate Generic Tagged Array (GTA) files.
@end direntry

@finalout
@titlepage
@title Bino
@subtitle A 3D video player with multi-display support.
@subtitle Version @value{VERSION}, @value{UPDATED}
@author The Bino developers
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@contents
@end ifnothtml

@ifnottex
@node Top
@top GTA Tool
@insertcopying
@end ifnottex

@ifhtml
Short Contents:
@end ifhtml
@menu
* Overview::
* Examples::
@end menu
@ifhtml
@contents
@end ifhtml

@node Overview
@chapter Overview

Gtatool (@code{gta}) manipulates Generic Tagged Arrays (GTAs).

A GTA is an n-dimensional @emph{array} with metadata in the form of @emph{tags}
(key-value pairs).

A GTA file or @emph{stream} contains a sequence of such arrays.

Each array has n @emph{dimensions}. For example, images have 2 dimensions, and
volume data sets have 3.

Each array element consists of m @emph{components}. These components can have
different types. For example, image data is commonly stored using 3 components
of type @code{uint8}.

The @code{gta} tool provides commands to manipulate GTAs. These commands are
organized in the following categories:
@itemize
@item Commands that operate on element component level.@*
For example, these commands add or remove components, or change their types.
@item Commands that operate on dimension level.@*
For example, these commands add or remove dimensions, or change their sizes.
@item Commands that operate on array level.@*
For example, these commands create or compare arrays, or modify array tags.
@item Commands that operate on stream level.@*
For example, these commands add or remove arrays.
@item Commands to convert from/to other file formats.@*
These commands import and export GTAs from/to many different file formats.
@end itemize

Use @code{gta help} to get a list of available commands, and @code{gta help
cmd} to get help for command @code{cmd}.

(Alternatively, you can use @code{gta --help} and @code{gta cmd --help}.)


@node Examples
@chapter Examples

@section Average of Arrays

Say you recorded 100 camera frames in a file called @code{frames.gta}, and you
want to compute the average of these 100 frames.

First, produce separate files @code{000.gta}, @dots{}, @code{099.gta}:
@example
$ gta stream-split %3N.gta frames.gta
@end example

Then add them all up and store the result in @code{sum.gta}:
@example
$ gta combine -m add ???.gta > sum.gta
@end example

Then divide by the number of frames to get the average:
@example
$ gta component-compute -e 'c0 = c0 / 100' sum.gta > avg.gta
@end example

This works fine with floating point values. If your array uses integer
component types, e.g. uint8 for RGB, you may need to convert to floating point
first (using @code{component-convert}) so that the sum does not overflow.

@bye
