PointFromTokensReader module

Module contents

template<typename PointT, typename SourceIterT>
class PointFromTokensReader : public tracktable::GenericReader<PointT>

Read points from lists of tokens.

PointFromTokensReader expects as its input an iterator that will yield iterator ranges. That is, each value of the iterator is a (begin, end) pair of iterators that will produce a set of tokens for one point.

Think of it with this common use case. Somewhere upstream you are reading lines from a text file. Your reader takes lines from the file and separates each line into a list of tokens using some delimiter. PointFromTokensReader takes each of those lists of tokens, one list at a time, and turns it into a point of some user-requested type.

Public Types

typedef PointT point_type
typedef SourceIterT source_iterator_type
typedef boost::shared_ptr<point_type> point_shared_ptr_type

Public Functions

inline PointFromTokensReader()

Instantiate a default PointFromTokensReader.

inline PointFromTokensReader(const PointFromTokensReader &other)

Copy contructor, create a reader with a copy of another

Parameters:

other – [in] PointFromTokensReader to copy from

inline PointFromTokensReader(source_iterator_type const &start, source_iterator_type const &finish)

Instantiate a reader with a start and finish points

Parameters:

  • start – [in] Iterator to start from

  • finish – [in] Iterator to end at

inline virtual ~PointFromTokensReader()

Destructor.

inline PointFromTokensReader &operator=(PointFromTokensReader const &other)

Assign a PointFromTokensReader to the value of another.

Parameters:

other – [in] PointFromTokensReader to assign value of

Returns:

Reader with the new assigned value

inline bool operator==(PointFromTokensReader const &other) const

Check whether one reader is equal to another by comparing all the properties.

Two readers are equal if all of their properties are equal.

Parameters:

other – [in] PointFromTokensReader for comparison

Returns:

Boolean indicating equivalency

inline bool operator!=(PointFromTokensReader const &other) const

Check whether two PointFromTokensReader are unequal.

Parameters:

other – [in] PointFromTokensReader for comparison

Returns:

Boolean indicating equivalency

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_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 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 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 int coordinate_column(int coordinate) const

Return which column has the given corrdinate

Returns:

Column that contains the given coordinate

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 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 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_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_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 void clear_coordinate_assignments()

Clear all of the coordinate assignments

inline void set_warnings_enabled(bool onoff)

Enable/disable warnings during parsing.

We may run into type mismatches and bad casts while we’re parsing headers and data. This flag determines whether or not warnings will be printed.

Parameters:

onoff – [in] Warnings are on / off

inline bool warnings_enabled() const

Check whether warnings are enable

Returns:

Whether or not warnings are on

inline bool ignore_header() const

Check whether to see if the header should be ignored when reading input

Returns:

Boolean whether or not the header should be ignored

inline void set_ignore_header(bool onoff)

Enable/disable ignoring the header during parsing.

Parameters:

onoff – [in] Header parsing on / off

inline void set_input_range(source_iterator_type my_begin, source_iterator_type my_end)

Set the beginning and the end of the input range

Parameters:

  • my_begin – [in] The iterator to use for the start of input

  • my_end – [in] The iterator to use for the end of input

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 tracktable::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(tracktable::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.

inline void set_point_count_log_enabled(bool onoff)

Enable/disable logging of point count on read

When set to true (the default), the point reader will print out the number of points successfully read and the number of errors to the info log channel when the end of the input is reached.

This function is provided because there are cases like the trajectory reader where this results in thousands of lines of spam because the reader is invoked for every trajectory separately.

Parameters:

onoff – [in] Boolean flag: ‘true’ means ‘yes, log statistics’

inline bool point_count_log_enabled() const

Get the status of the point count log

Retrieve PointCountLogEnabled. When set to true, this flag will print out how many points are read successfully and how many are lost due to error.

Returns:

Whether or not point count logging is enabled

Protected Types

typedef rw::detail::PropertyAssignmentMap PropertyAssignmentMap
typedef std::vector<settings::string_type> string_vector_type

Protected Functions

inline virtual point_shared_ptr_type next_item()

Increment the iterator the next item to be read in

Returns:

The next item

inline void configure_reader_from_header(string_vector_type const &tokens)

Configure the reader based on information contained in the input header

Parameters:

tokens – [in] Tokens from the header to be read in

inline void configure_coordinate_assignments(bool object_id_present, bool timestamp_present, std::size_t expected_dimension)

Configure the coordinates based on information parsed from the input header

Parameters:

  • object_id_present – [in] Boolean indicating if object ID is present

  • timestamp_present – [in] Boolean indicating if timestamp is present

  • expected_dimension – [in] Dimension coordinates are expected to be in

inline void configure_field_assignments(rw::detail::PointHeader const &header, std::size_t first_property_column)

Configure the fields based on information parsed from the input header

Parameters:

  • header – [in] Header containing the field information

  • first_property_column – [in] First column containing a property

inline void get_tokens_from_input(string_vector_type &tokens)

Get specified tokens from the input

Parameters:

tokens – [in] Tokens to get from input

inline void populate_coordinates_from_tokens(string_vector_type const &tokens, point_shared_ptr_type point)

Populated the coordinates from input tokens

Parameters:

  • tokens – [in] Tokens to use for population

  • point – [in] Point containing coordinates

inline void populate_properties_from_tokens(string_vector_type const &tokens, point_shared_ptr_type point)

Populated the properties from input tokens

Parameters:

  • tokens – [in] Tokens to use for population

  • point – [in] Point containing properties

Protected Attributes

IntIntMap CoordinateMap
PropertyAssignmentMap FieldMap
source_iterator_type SourceBegin
source_iterator_type SourceEnd
int ObjectIdColumn
int TimestampColumn
bool IgnoreHeader
bool WarningsEnabled
bool PointCountLogEnabled
PropertyConverter PropertyReadWrite
int NumPoints
int NumParseErrors