PointReader module

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++/RW/Tests/test_integrated_trajectory_point_reader.cpp) for an example of how to use it.

Public Types

typedef point_reader_type::iterator iterator

Public Functions

inline PointReader()

Instantiate PointReader using a 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.

inline PointReader(std::istream &infile)

Instantiate PointReader using a file and 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.

Parameters:

infile – [in] File to read points from

inline PointReader(PointReader const &other)

Copy contructor, create a PointReader with a copy of another

Parameters:

other – [in] PointReader to copy from

inline virtual ~PointReader()

Destructor.

inline 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.

inline 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:

comment – [in] Single character

inline std::string comment_character() const

Retrieve current value of comment character.

This function invalidates any outstanding iterators.

Returns:

Current value of comment character

inline 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:

_input – [in] Stream from which we will read points

inline std::istream &input() const

Retrieve the current input stream.

Bug:

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

Returns:

Stream being used for input.

inline 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:

delimiter – [in] String containing desired delimiter character

inline string_type field_delimiter() const

Retrieve the current field delimiter character.

Returns:

String containing delimiter

inline void set_x_column(int column)

Identify the column that will be the X coordinate.

Parameters:

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

inline void set_y_column(int column)

Identify the column that will be the Y coordinate.

Parameters:

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

inline void set_z_column(int column)

Identify the column that will be the Z coordinate.

Parameters:

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

inline void set_longitude_column(int column)

Identify the column that will be the longitude coordinate.

Parameters:

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

inline void set_latitude_column(int column)

Identify the column that will be the latitude coordinate

Parameters:

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

inline int x_column() const

Get the column number that will be the X coordinate.

Returns:

Column number in the input file (starts at 0)

inline int y_column() const

Get the column number that will be the Y coordinate.

Returns:

Column number in the input file (starts at 0)

inline int z_column() const

Get the column number that will be the Z coordinate.

Returns:

Column number in the input file (starts at 0)

inline int longitude_column() const

Get the column number that will be the longitude coordinate.

Returns:

Column number in the input file (starts at 0)

inline int latitude_column() const

Get the column number that will be the latitude coordinate.

Returns:

Column number in the input file (starts at 0)

inline 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:

• coordinate – [in] Index of coordinate to set

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

inline bool has_coordinate_column(int coordinate) const

Check to see if there is a coordindate column

Returns:

Boolean indicating that there exists a coordinate column

inline int coordinate_column(int coordinate) const

Return which column has the given corrdinate

Returns:

Column that contains the given coordinate

inline void clear_coordinate_assignments()

Clear all of the coordinate assignments

inline void set_object_id_column(int column)

Set 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:

column – [in] Which column contains object IDs

inline void set_timestamp_column(int column)

Set 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:

column – [in] Which column contains timestamps

inline int object_id_column() const

Identify the column that will be used for object IDs.

Column indices start at zero.

Returns:

The column containing the object ID

inline int timestamp_column() const

Identify the column that will be used for timestamps.

Column indices start at zero.

Returns:

The column containing the timestamo

inline 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_string_field_column("model_name", 3);

This function invalidates any outstanding iterators.

Parameters:

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

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

inline void set_real_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_real_field_column("mileage", 4);

This function invalidates any outstanding iterators.

Parameters:

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

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

inline void set_time_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);

This function invalidates any outstanding iterators.

Parameters:

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

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

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

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

Parameters:

field – [in] String name of field

Returns:

True/False depending on whether field is present or not

inline bool has_real_field_column(std::string const &field) const

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

Parameters:

field – [in] String name of field

Returns:

True/False depending on whether field is present or not

inline bool has_time_field_column(std::string const &field) const

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

Parameters:

field – [in] String name of field

Returns:

True/False depending on whether field is present or not

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

Retrieve the column assignment for a real-valued field.

Parameters:

field – [in] String name of field

Returns:

Integer column index for field or -1 if not present

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

Retrieve the column assignment for a string field.

Parameters:

field – [in] String name of field

Returns:

Integer column index for field or -1 if not present

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

Retrieve the column assignment for a time field.

Parameters:

field – [in] String name of field

Returns:

Integer column index for field or -1 if not present

inline 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.

Returns:

Iterator to first parsed point

inline 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.

Returns:

Iterator past end of point sequence

inline void set_timestamp_format(string_type const &format)

Set the format of the timestamp

Parameters:

format – [in] String containing the format of the time stamp

inline string_type timestamp_format() const

Retrieve the format of the timestamp

Returns:

The timestamp format

inline void set_null_value(string_type const &value)

Set the format of the timestamp

Parameters:

value – [in] String value to use for NULL

inline string_type null_value() const

Retrieve the null value

Returns:

The null value

inline IntIntMap &__coordinate_assignments()

This method is for the Python wrappers.

In C++-land this explicitly breaks encapsulation. DON’T USE IT!

In Python-land it make for a much more Pythonic interface.

inline void __set_coordinate_assignments(IntIntMap const &cmap)

This method is for the Python wrappers.

In C++-land this explicitly breaks encapsulation. DON’T USE IT!

In Python-land it make for a much more Pythonic interface.

Private Types

typedef PointT point_type

typedef tracktable::LineReader line_reader_type

typedef tracktable::SkipCommentsReader<line_reader_type::iterator> skip_comments_reader_type

typedef tracktable::StringTokenizingReader<skip_comments_reader_type::iterator> string_tokenizer_type

typedef tracktable::PointFromTokensReader<point_type, string_tokenizer_type::iterator> point_reader_type

Private Members

line_reader_type LineReader

skip_comments_reader_type SkipCommentsReader

string_tokenizer_type StringTokenizer

point_reader_type PointTokenReader