tracktable.script_helpers.argument_groups package

These are the predefined argument groups that come with Tracktable.

tracktable.script_helpers.argument_groups.dt_point_loader module

Arguments for the delimited text point reader.

Use this group as follows:

from tracktable.script_helpers import argument_groups, argparse
my_parser = argparse.ArgumentParser()
argument_groups.use_group('dt_point_loader', my_parser)

Arguments:

--delimiter CHARACTER

Single character delimiter for fields

--comment-character CHARACTER

Single character indicating ‘skip this line’ when found as the first non-whitespace character on a line

--domain NAME Name of domain (terrestrial, cartesian2d, cartesian3d)

for points to be read

--longitude-column COL

Populate longitude with the contents of column COL

--latitude-column COL

Populate latitude with the contents of column COL

--x-column COL

Populate X coordinate with the contents of column COL

--y-column COL

Populate Y coordinate with the contents of column COL

--string-field-column NAME COL

Populate field NAME with column COL as a string

--numeric-field-column NAME COL

Populate field NAME with column COL as a number

--timestamp-field-column NAME COL

Populate field NAME with column COL as a timestamp. Not the same as the timestamp column.

--object-id-column COL

Populate the point’s object ID with column COL. Only applies to trajectory points.

--timestamp-column COL

Populate the point’s timestamp with column C. Only applies to trajectory points.

tracktable.script_helpers.argument_groups.dt_point_loader.install_group()

Create the argument group for DelimitedTextPointReader.

This function is called automatically when the argument_groups module is loaded.

tracktable.script_helpers.argument_groups.mapmaker module

Command-line options for creating and decorating maps.

The Mapmaker argument group contains (almost) everything we think you might need in order to draw a map of part of the Earth, including decorating it with borders and cities. It can also be used to specify a map for a 2D Cartesian data set, albeit with some awkwardness. This will be fixed soon.

Arguments:

--domain NAME

Point domain for your data. This will be one of ‘terrestrial’, ‘cartesian2d’, ‘cartesian3d’.

--map NAME

Name of map that you want. See tracktable.render.maps.available_maps() for options. There is also a “custom” map type where you supply your own bounding box.

--omit-coastlines

Do not draw continent boundaries

--omit-countries

Do not draw country borders

--omit-states

Do not draw US/Canada state borders

--omit-lonlat

Do not draw longitude/latitude lines

--lonlat-spacing NUMBER

Spacing (in degrees) between longitude/latitude lines

--draw-cities-larger-than NUMBER

Draw all cities on the map with population larger than N

--draw-largest-cities NUMBER

Draw the largest N cities (by population) on the map

--continent-color COLOR

Color (name or hex string) for continental coastlines

--continent-linewidth NUMBER

Line width (in points) for continental coastlines

--continent-zorder NUMBER

Layer (Z-order, integer) for continental coastlines. Higher numbers are drawn on top of lower numbers.

--country-color COLOR

Color (name or hex string) for country borders

--country-linewidth NUMBER

Line width (in points) for country borders

--country-zorder NUMBER

Label (Z-order, integer) for country borders. Higher numbers are drawn on top of lower numbers.

--land-color COLOR

Color (name or hex string) for land masses

--sea-color COLOR

Color (name or hex string) for bodies of water

--state-color COLOR

Color (name or hex string) for state borders

--state-linewidth NUMBER

Line width (in points) for state borders

--state-zorder NUMBER

Label (Z-order, integer) for state borders. Higher numbers are drawn on top of lower numbers.

--city-label-size NUMBER

Font size (in points) for city labels

--city-dot-size NUMBER

Size (in points) for dots representing cities on map

--city-dot-color COLOR

Color (name or hex string) for dots onmap representing cities

--city-label-color COLOR

Color (name or hex string) for city labels on map.

--map-bbox X_MIN X_MAX Y_MIN Y_MAX

Axis-aligned bounding box for map.

--map-projection STRING

Map projection string for Basemap. Defaults to ‘mill’ (Miller cylindrical).

tracktable.script_helpers.argument_groups.mapmaker.install_group()

Register the Mapmaker argument group.

This function is called when the argument_groups module is imported by dint of being listed in __init__.py.

tracktable.script_helpers.argument_groups.movie_rendering module

Parameters for movie rendering.

This argument group contains just those parameters that are specific to movie rendering such as the encoder to use, frames per second, duration, etc. Image-related stuff such as resolution and DPI is in the ‘image’ argument group.

Note that the timezone label is not a natural fit for this argument group. I haven’t yet figured out where else to put it.

Arguments:

--encoder NAME

Which movie encoder to use. Defaults to FFMPEG.

--duration NN

How many seconds long the movie should be

--fps NN

How many frames per second the movie should contain

--start-time TIME

Start time for the movie in ‘YYYY-MM-DD HH:MM:SS+XX’ format (defaults to start time of data)

--end-time TIME

End time for the movie in ‘YYYY-MM-DD HH:MM:SS+XX’ format (defaults to end time of data)

--encoder-args STRING

Extra args to pass to the encoder (specify as a single string)

--utc-offset NN

UTC offset for displayed timestamp (will convert to local time zone)

--timezone-label STRING

Time zone label to be added to clock

tracktable.script_helpers.argument_groups.movie_rendering.install_group()

Standard method - define the Movie Rendering argument group

tracktable.script_helpers.argument_groups.parallel module

Options for parallel movie rendering.

This argument group allows you to set the number of processes and (eventually) maximum memory that you’re willing to use when rendering movies in parallel.

Arguments:

--processors NUMBER

How many processes to spawn. The default value (0) means ‘one process per detected core on the system’.

tracktable.script_helpers.argument_groups.parallel.install_group()

Standard method - define the Parallel Movie Rendering argument group

tracktable.script_helpers.argument_groups.trajectory_assembly module

Options for creating trajectories from points.

This argument group lets you control the parameters for the algorithm that assembles sequences of time-stamped points into continuous trajectories.

Arguments:

--separation-distance NUMBER

A gap of at least this many units between successive points will result in a new trajectory.

--separation-time NUMBER

A gap of at least this many MINUTES between successive points will result in a new trajectory.

--minimum-length NUMBER

Discard finished trajectories with fewer than this many points.

tracktable.script_helpers.argument_groups.trajectory_assembly.install_group()

Create and populate the argument group for trajectory assembly.

tracktable.script_helpers.argument_groups.trajectory_rendering module

Options for rendering trajectories onto a map.

Arguments:

--trajectory-color-type ["scalar", "constant"]

Whether to use a function (scalar) or constant color for trajectories

--trajectory-color-function NAME

Function to generate trajectory color. Default is ‘progress’, a function that is 0 at the beginning of a trajectory and 1 at its end. Requires --trajectory-color-type scalar.

--trajectory-color COLOR

Constant color for trajectories. Requires --trajectory-color-type constant.

--trajectory-colormap NAME

Colormap to use to color trajectories. Use one of the Matplotlib standard colormaps or one of Tracktable’s color maps from tracktable.render.colormaps.

--trajectory-zorder NUMBER

Layer number for trajectories. Higher-numbered layers are rendered on top of lower-numbered ones.

--decorate-trajectory-head

Draw a dot at the head of each trajectory.

--trajectory-head-color COLOR

Color (name or hex string) for the dot at the head of the trajectory. Requires ‘–decorate-trajectory-head’. You can also specify ‘body’ to use the same color as the first segment of the trajectory.

--trajectory-head-dot-size NUMBER

Size (in points) of the dot to render at the head of each trajectory. Requires --decorate-trajectory-head.

--trajectory-linewidth NUMBER

Trajectory linewidth in points. You can also specify ‘taper’, in which case trajectory linewidth will start at the value of --trajectory-initial-linewidth and end at --trajectory-final-linewidth.

--trajectory-initial-linewidth NUMBER

Width (in points) at the head of the trajectory. Requires --trajectory-linewidth taper.

--trajectory-final-linewidth NUMBER

Width (in points) at the end of the trajectory. Requires --trajectory-linewidth taper.

--scalar-min NUMBER

Scalar value to map to bottom of color map. Requires --trajectory-color-type scalar.

--scalar-max NUMBER

Scalar value to map to top of color map. Requires --trajectory-color-type scalar.

tracktable.script_helpers.argument_groups.trajectory_rendering.install_group()

Standard method - define the Trajectory Rendering argument group

tracktable.script_helpers.argument_groups.utilities module

INTERNAL: Implementations for manipulating argument groups

Module contents

Argument groups: sets of co-occurring command line arguments

The various capabilities in Tracktable tend to have several arguments. If we want to expose those in scripts we wind up making a lot of calls to argparse and then spending a lot of time handling the arguments. This file collects utilities for

1. defining sets of arguments for later use,

(2) creating example ‘response files’ (text files that contain lots of ‘–arg value’ pairs) for the user to customize,

(3) performing initial parsing of a set of arguments to recursively expand response files.

Here is an example of how to create and populate an argument group:

create_argument_group('example', title='Sample Argument Group', description='This argument group exists to demonstrate what response files look like.')
add_argument('example', [ '--string-arg', '-s' ], help='An argument with a string value', default='Foo!')
add_argument('example', [ '--integer-arg', '-i' ], help='An integer argument', default=3)
add_argument('example', [ '--other' ], help='A required other argument with no default', required=Tru)

tracktable.script_helpers.argument_groups.create_argument_group(group_name, title=None, description=None)

Register a new, empty group of arguments

Arguments to configure different capabilities tend to come in groups. For example, movie-making includes frames per second, movie duration, encoder type and encoder options. This function lets you create such subject-related groups.

Note that this function only creates the group. You still have to populate it using register_argument (q.v.).

Parameters

• group_name (string) – Name of the group you want to add.

• title (string) – Title of the group. Not required but highly recommended.

• description (string) – Description / help text. Not required but highly recommended.

Returns

The name of the group just added.

tracktable.script_helpers.argument_groups.add_argument(group_name, option_names, **kwargs)

Add a single command-line argument to a group.

Parameters

• group_name (string) – Name for conceptual group of arguments (such as ‘movie’ for movie-making parameters)

• option_names (list) – A list of command-line options that can be used to specify this argument (such as [ ‘–frame-rate’, ‘-f’ ])

• other arguments will be passed straight to argparse.add_argument() when this argument group is requested. (All) –

Returns

The name of the argument just added.

Raises

KeyError – the specified argument group does not exist.

Examples

>>> add_argument('movies', [ '--frame-rate', '-f' ],
                 help='Desired frame rate for movie',
                 type=int,
                 default=30)
'--frame-rate'

>>> add_argument('nonexistent_group', [ '--foo', '-g' ])
XXX INSERT ERROR MESSAGES

tracktable.script_helpers.argument_groups.available_argument_groups()

Return a list of all available argument groups.

Parameters

None –

Returns

A list of strings, each the name of a registered argument group

tracktable.script_helpers.argument_groups.use_argument_group(group_name, parser)

Add a group of arguments to a parser.

Parameters

• group_name – Name of the desired group of arguments

• parser – An instance of argparse.ArgumentParser

Returns

Parser after the arguments have been added

Raises

KeyError – the desired argument group does not exist

Once you have registered one or more arguments in a group, call use_arguments to add them to a parser. They will be added to a group in that parser.

Examples: XXX TODO

tracktable.script_helpers.argument_groups.extract_arguments(group_name, parsed_args, switch_character='-')

Extract a group of arguments from a Namespace into a dict

Argument groups make it easy to include a batch of options all at once. This function is the next step: after you’ve used argparse.ArgumentParser to parse a set of command-line arguments, you use extract_arguments to extract a group of arguments into a dict. This dict can then be passed on to a function as a set of keyword arguments.

The difference between this and calling vals() on the namespace returned by parse_args() is that this pulls out just the arguments associated with the specified group.

Parameters

• group_name – A string naming the group to extract

• parsed_args – A Namespace object returned from argparse.ArgumentParser.parse_args()

• switch_character – Character used to prefix switches, e.g. ‘-‘ for options like ‘–foo’ and ‘-f’

Returns

A dict() whose names are the destinations (*) associated with the command-line arguments and whose values are the values from the command line

Raises

KeyError – The desired argument group doesn’t exist