Edit me

Introduction

Anchor can be used from the command-line as follows:

anchor [options] [experimentFile.xml]

If an experimentFile.xml isn’t specified, the default experiment is employed, with default inputs, task, outputs.

Major options

The most important command-line options are:

Option Description
-i arg Changes inputs, where arg = extension or wildcards or input-directory path or path to BeanXML
-t [arg] Changes the task, where arg = predefined-task-name or path to BeanXML
-o arg Changes outputs, where arg = path to an output-directory or path to BeanXML
-h Displays help message with all command-line options.

Input options

Note:

  • Each input file is assigned a unique name, which subsequently determines corresponding output file paths.

  • By default, this is inferred from a pattern in the input filenames (e.g. an incrementing integer, varying string etc.) in a minimal way, while capturing the varying elements.

Options useful for influencing inputting:

Option Description
-i arg Changes inputs, where arg = extension or wildcards or input-directory path or path to BeanXML
-ic Copies any files unused as inputs (but existing within the input directory) to the output directory.
-ii range Subsets the file-path pattern. Type anchor and look for variable-components ${0}, ${1} etc.
Specify which component(s) to retain via a single index or index-range ala grouping. Zero-indexed.
-il num Uses only the initial num inputs (when an integer), or (num*100)% when in interval (0.0,1.0)
-ip Derives the name instead from the entire relative file-path excluding the file extension.
e.g. it selects subdir/prefix_234 rather than 234 (by default, only what varies among filenames).
-ir num Randomly samples num inputs (when an integer), or (num*100)% when in interval (0.0,1.0)
-is Shuffles (randomizes) the order of the inputs.

Output options

Note:

  • tasks produce one or more outputs, with certain outputs enabled by default.
  • the file-format used for any given is determined by rules in defaultBeans.xml.

Options useful for influencing outputting:

Option Description
-o arg Changes outputs where arg = path to an output-directory or path to BeanXML
-oa Enables all outputs.
-oc Disables opening the output directory in the desktop (upon experiment end).
-od outputName(s) Disables specific output(s). Multiple outputs are comma-separated.
-oe outputName(s) Enables specific output(s). Multiple outputs are comma-separated.
-of formatExtension Suggests an output image file format: e.g -of jpg or -of ome.xml
-on Outputs with an incrementing number instead of the input name.
(useful for creating sequences of images)
-oo arg Like -o arg but omits the subdirectory with experiment name / version.
-os Replaces directory separators in the output file-path with an underscore.

Task options

Options useful for tasks:

Option Description
-t [arg] Changes the task, where arg = predefined-task-name or path to BeanXML
-tp number Suggests a maximum number of CPU processors.
-st Prints the names of predefined tasks that can be used with -t.
-pg range Activates grouping from a subset of each input’s identifier (see below).
-ps size Suggests image size (e.g. 1024x768) or a scaling factor (e.g.0.5)
- The order of dimensions is always widthxheight
- No scaling in the z-dimension is supported.
- Omitting a dimension resizes to the width/height and preserves aspect-ratio e.g. 200x or x50
- A trailing plus character preserves aspect ratio maximally within dimensions e.g. 1000x500+

The options beginning with -p are parameters that are optionally used only by specific tasks.

Debug options

Options useful for debugging:

Option Description
-d [string] Enables debug-mode: runs only the first available input [whose name contains string].
-l path Logs initial BeanXML errors in greater detail to a file-path
-sa Shows additional command-line option information, otherwise executes as normal.

Application information options

Options to show general application information are:

Option Description
-h Displays help message with all command-line options.
-v Displays version and authorship information.

Grouping

For certain tasks, the -pg option activates grouping.

This is similar to a GROUP BY in relational databases, and aggregates inputs together based upon a common key.

This key is derived from the identifier associated with each input, best illustrated by example.

Consider inputs with the corresponding identifiers (usually inferred from patterns in the file-paths):

france/paris/001
france/paris/002
france/paris/003
france/lyon/001
france/lyon/002
france/countryMap
spain/madrid/image1
spain/madrid/image2

Each identifier is split into its elements: france/countryMap has two elements; all others have three.

A subset of element(s) can then be derived from these elements, depending on the indices set on -pg’s argument.

The argument may be either a single index or a range. Zero-indexed. Negatives count backwards from the end.

Examples:

  • -pg 0 (first only) would produce [france, france, france, france, france, spain, spain]
  • -pg -1(last only) would produce [001, 002, 003, 001, 002, countryMap, image1, image2]
  • -pg 0:-2 (from first to second-last) would produce [france/paris, france/paris, france/paris, france/lyon, france/lyon, france, spain/madrid, spaid/madrid]
  • -pg :-2 (until second-last) is identical to the above.
  • -pg: 1: (from second) would produce [paris/001, paris/002, paris/003, lyon/001, lyon/002, countryMap, madrid/image1, madrid/image2]
Tags: getting_started