TracktableIO module

This module contains clsases that read and write points and trajectories. In Tracktable 0.9 we provide PointReader, a C++ class templated on point type that can handle points with arbitrary dimension and named properties.

Module contents

template<typename PointT>
class PointReader

Read points from files.

This reader wraps the following pipeline:

  • Read lines from a text file

  • Skip any lines that begin with a designated comment character (‘#’ by default)

  • Tokenize each line using specified delimiters (whitespace by default)

  • Create a point (user-specified type) from each tokenized line

  • Return the resulting points via a C++ iterator

You will use set_input() to supply an input stream, set_comment_character() to configure which lines to skip, set_delimiter() to specify how to turn lines into tokens, and set_column_for_field() to assign columns in the data file to fields (object ID, longitude, latitude, etc) on the point.

Take a look at the test case for this class (in C++/IO/Tests/test_integrated_trajectory_point_reader.cpp) for an example of how to use it.

Public Functions

void set_default_configuration()

Default reader configuration.

If you are reading BasePoints, this sets coordinates 0 to d-1 (D is the point’s dimension) using columns 0 to d-1.

If you are reading TrajectoryPoints, column 0 is the object ID, column 1 is the timestamp, and columns 2 through D+1 (inclusive) are the coordinates.

These are the default settings. You can override any or all of them after you instantiate the reader.

void set_comment_character(std::string const &comment)

Specify comment character for skipping lines.

A line is a comment if and only if its first non-whitespace character is the comment character (‘#’ by default). We will skip such lines entirely. We do not handle inline or trailing comments: a line will either be included in its entirety or skipped completely.

Parameters

  • [in] comment: Single character

std::string comment_character() const

Retrieve current value of comment character.

This function invalidates any outstanding iterators.

Return

Current value of comment character

void set_input(std::istream &_input)

Supply input stream from delimited text source.

We read our input from C++ std::istreams. The stream you supply will be traversed exactly once.

Parameters

  • [in] input: Stream from which we will read points

std::istream &input() const

Retrieve the current input stream.

BUG: We currently have no way to indicate whether the stream is valid.

Return

Stream being used for input.

void set_field_delimiter(string_type const &delimiter)

Set one character for use as a field delimiter.

The character in the argument to this function will be treated as a field delimiter in the input.

This function invalidates any outstanding iterators.

Parameters

  • [in] delimiter: String containing desired delimiter character

string_type field_delimiter() const

Retrieve the current field delimiter character.

Return

String containing delimiter

void set_x_column(int column)

Identify the column that will be the X coordinate.

Parameters

  • [in] column: Column number in the input file to use (starts at 0)

void set_y_column(int column)

Identify the column that will be the Y coordinate.

Parameters

  • [in] column: Column number in the input file to use (starts at 0)

void set_z_column(int column)

Identify the column that will be the Z coordinate.

Parameters

  • [in] column: Column number in the input file to use (starts at 0)

void set_longitude_column(int column)

Identify the column that will be the longitude coordinate.

Parameters

  • [in] column: Column number in the input file to use (starts at 0)

void set_latitude_column(int column)

Identify the column that will be the latitude coordinate.

Parameters

  • [in] column: Column number in the input file to use (starts at 0)

int x_column() const

Get the column number that will be the X coordinate.

Return

Column number in the input file (starts at 0)

int y_column() const

Get the column number that will be the Y coordinate.

Return

Column number in the input file (starts at 0)

int z_column() const

Get the column number that will be the Z coordinate.

Return

Column number in the input file (starts at 0)

int longitude_column() const

Get the column number that will be the longitude coordinate.

Return

Column number in the input file (starts at 0)

int latitude_column() const

Get the column number that will be the latitude coordinate.

Return

Column number in the input file (starts at 0)

void set_coordinate_column(int coordinate, int column)

Configure the mapping from columns to coordinates.

This is the lowest-level interface to setting coordinates in the reader. Use set_x_coordinate_column/set_longitude_column and friends if possible (i.e. if you’re in the terrestrial or 2D Cartesian domain).

Let’s suppose that your X coordinate is in column 12 of your file, your Y coordinate is in column 20 and your Z coordinate is in column 32. The following code snippet illustrates how to set this up in the reader:

tracktable::PointReader<MyPoint3D> reader;
reader.set_coordinate_column(0, 12); // X coordinate
reader.set_coordinate_column(1, 20); // Y coordinate
reader.set_coordinate_column(2, 32); // Z coordinate

Calling this function invalidates any outstanding iterators.

Note

Column and coordinate indices start at zero.

Parameters

  • [in] coordinate: Index of coordinate to set

  • [in] column: Index of column in list of tokens

void set_object_id_column(int column)

Identify the column that will be used for object IDs.

This column in the input stream will be used to populate the object_id field in trajectory points. Column indices start at zero.

Parameters

  • [in] column: Which column contains object IDs

void set_timestamp_column(int column)

Identify the column that will be used for timestamps.

This column in the input stream will be used to populate the timestamp field in trajectory points. Column indices start at zero.

Parameters

  • [in] column: Which column contains timestamps

void set_string_field_column(std::string const &field, int column)

Configure the mapping from columns to data fields.

Some points have the ability to store named properties. Use this method to assign columns in the data file to named properties on points.

The following lines of code show an example.

tracktable::PointReader<MyPointType> reader;
reader.set_object_id_column(0);
reader.set_time_field_column("last_seen", 2);
reader.set_string_field_column("model_name", 3);
reader.set_real_field_column("mileage", 4);

This function invalidates any outstanding iterators.

Parameters

  • [in] field: Name of field to populate on point object

  • [in] column: Index of column in list of tokens

bool has_string_field_column(std::string const &field) const

Check to see where a field is present in the field map.

Return

True/false depending on whether field is present or not

Parameters

  • [in] field: String name of field

int real_field_column(std::string const &field) const

Retrieve the column assignment for a real-valued field.

Return

Integer column index for field or -1 if not present

Parameters

  • [in] field: String name of field

int string_field_column(std::string const &field) const

Retrieve the column assignment for a string field.

Return

Integer column index for field or -1 if not present

Parameters

  • [in] field: String name of field

int time_field_column(std::string const &field) const

Retrieve the column assignment for a string field.

Return

Integer column index for field or -1 if not present

Parameters

  • [in] field: String name of field

iterator begin()

Return an iterator to the first parsed point.

This will take the parameters you’ve established for the input stream, comment character, delimiters and field/column mapping and start up the whole parsing pipeline. You can iterate through in the standard C++ fashion until you reach the end().

Note that any changes you make to the parser configuration will invalidate existing iterators.

Return

Iterator to first parsed point

iterator end()

Return an iterator to detect when parsing has ended.

This iterator is guaranteed to not point at any valid TrajectoryPoint. The only time when begin() == end() will be when all points have been parsed from the input stream.

Return

Iterator past end of point sequence