Input

Point Input

There are three ways to get point data into Tracktable:

  1. Instantiate and populate BasePoint and TrajectoryPoint objects by hand.

  2. Load points from a delimited text file.

  3. Create points algorithmically.

Manually Instantiate Points

For instructions on manually instantiating both BasePoint and TrajectoryPoint objects refer to the Point Classes section of the Python user guide.

Loading Points from Delimited Text

Tracktable has a flexible point reader for delimited text files. Each point domain provides two versions of it, one for loading base points (coordinates only) and one for loading trajectory points. As of Tracktable 1.7, there is a generalized trajectory loader that will automatically load CSV, TSV or TRAJ files into either a list of trajectory points or trajectories.

General Loader
 1from tracktable.rw.load import load_trajectories
 2from tracktable_data.data import retrieve
 3
 4filename = retrieve('SampleFlightsUS.csv')
 5# file = retrieve('SampleFlightsUS.tsv')
 6
 7# To get the trajectory points set the `return_trajectory_points` flag
 8trajectory_points = load_trajectories(filename, return_trajectory_points=True)
 9
10# To get the underlying generator unset the `return_list` flag
11trajectory_points = load_trajectories(filename, return_list=False)
12
13# To get the assembled trajectories just pass the file
14trajectories = load_trajectories(filename)

Note

For posterity, the example for creating a CSV/TSV reader by hand has been preserved below for reference.

 1from tracktable.domain.terrestrial import TrajectoryPointReader
 2
 3with open(retrieve('SampleFlightsUS.csv'), 'rb') as infile:
 4    reader = TrajectoryPointReader()
 5    reader.input = infile
 6    reader.delimiter = ','
 7
 8    # Columns 0 and 1 are the object ID and timestamp
 9    reader.object_id_column = 0
10    reader.timestamp_column = 1
11
12    # Columns 2 and 3 are the longitude and
13    # latitude (coordinates 0 and 1)
14    reader.coordinates[0] = 2
15    reader.coordinates[1] = 3
16
17    # Column 4 is the altitude
18    reader.set_real_field_column("altitude", 4)
19
20    for point in reader:
21        # Do whatever you want with the points here

Algorithmically Creating Points

Important

To create points algorithmically we will need to supply (at a minimum) coordinates, a timestamp and an ID.

There are a handful of algorithmic point source generators within Tracktable. The most useful of which is TrajectoryPointSource which will generate points interpolated between a given start and finish point as shown by the example below. These points can then be assembled into trajectories which will be shown below but explained in further detail in the Trajectory Assembly section.

 1import itertools
 2from datetime import timedelta
 3
 4from tracktable.core import Timestamp
 5from tracktable.domain.terrestrial import TrajectoryPoint
 6from tracktable.feature.interpolated_points import TrajectoryPointSource
 7from tracktable.applications.assemble_trajectories import AssembleTrajectoryFromPoints
 8
 9albuquerque = TrajectoryPoint( -106.5, 35.25 )
10albuquerque.timestamp = Timestamp.from_string('2010-01-01 12:00:00')
11albuquerque.object_id = 'flight1'
12
13san_diego1 = TrajectoryPoint( -117.16, 32.67 )
14san_diego1.timestamp = Timestamp.from_string('2010-01-01 15:00:00')
15san_diego1.object_id = 'flight1'
16
17san_diego2 = TrajectoryPoint( -117.16, 32.67 )
18san_diego2.timestamp = Timestamp.from_string('2010-01-01 16:00:00')
19san_diego2.object_id = 'flight1'
20
21seattle = TrajectoryPoint( -122.31, 47.60 )
22seattle.timestamp = Timestamp.from_string('2010-01-01 19:00:00')
23seattle.object_id = 'flight1'
24
25denver = TrajectoryPoint( -104.98, 39.79 )
26denver.timestamp = Timestamp.from_string('2010-01-01 19:01:00')
27denver.object_id = 'flight1'
28
29new_york = TrajectoryPoint( -74.02, 40.71 )
30new_york.timestamp = Timestamp.from_string('2010-01-02 00:00:00')
31new_york.object_id = 'flight1'
32
33# Now we want sequences of points for each flight.
34abq_to_sd = TrajectoryPointSource()
35abq_to_sd.start_point = albuquerque
36abq_to_sd.end_point = san_diego1
37abq_to_sd.num_points = 180
38
39sd_to_sea = TrajectoryPointSource()
40sd_to_sea.start_point = san_diego2
41sd_to_sea.end_point = seattle
42sd_to_sea.num_points = 360 # flying very slowly
43
44denver_to_nyc = TrajectoryPointSource()
45denver_to_nyc.start_point = denver
46denver_to_nyc.end_point = new_york
47denver_to_nyc.num_points = 600 # wow, very densely sampled
48
49all_points = list(itertools.chain( abq_to_sd.points(),
50                                     sd_to_sea.points(),
51                                     denver_to_nyc.points() ))
52
53trajectory_assembler = AssembleTrajectoryFromPoints()
54trajectory_assembler.input = all_points
55trajectory_assembler.separation_time = timedelta(minutes=30)
56trajectory_assembler.separation_distance = 100
57trajectory_assembler_minimum_length = 10

Trajectory Input

There are two ways to get trajectory data into Tracktable:

  1. Instantiate and populate Trajectory objects by hand.

  2. Load trajectories from a delimited text file.

Manually Instantiate Trajectories

For instructions on manually instantiating Trajectory objects refer to the Trajectories section of the Python user guide.

Loading Trajectories from Delimited File

Tracktable has a flexible trajectory reader for delimited text files. Each point domain provides a trajectory reader. The trajectory reader functionality is the same across all point domains. Trajectories can be loaded from standard CSV and TSV delimited files as well as tracktable’s own TRAJ file type. Refer to the Tracktable Data page for more information about the TRAJ format. As of Tracktable 1.7, there is a generalized trajectory loader that will automatically load CSV, TSV or TRAJ files into either a list of trajectory points or trajectories.

General Loader
 1from tracktable.rw.load import load_trajectories
 2from tracktable_data.data import retrieve
 3
 4filename = retrieve('NYHarbor_2020_06_30_first_hour.traj')
 5
 6# To get the trajectory points set the `return_trajectory_points` flag
 7trajectory_points = load_trajectories(filename, return_trajectory_points=True)
 8
 9# To get just the trajectories just pass the file
10trajectories = load_trajectories(filename)

Note

For posterity the examples for creating TRAJ reader by hand have been preserved below for reference.

Trajectories From CSV
 1from tracktable.domain.terrestrial import TrajectoryReader
 2from tracktable_data.data import retrieve
 3
 4with open(retrieve('NYHarbor_2020_06_30_first_hour.traj'), 'rb') as infile:
 5    reader = TrajectoryReader()
 6    reader.input = inFile
 7
 8    # Columns 0 and 1 are the object ID and timestamp
 9    reader.object_id_column = 0
10    reader.timestamp_column = 1
11
12    # Columns 2 and 3 are the longitude and
13    # latitude (coordinates 0 and 1)
14    reader.coordinates[0] = 2
15    reader.coordinates[1] = 3
16
17    # Column 4 is the altitude
18    reader.set_real_field_column("altitude", 4)
19
20    # Note that by iterating over the reader, you get a collection of points together as
21    # trajectories. Just like the point reader, you can edit the delimiting character and
22    # comment character as well as the column properties.
23    for traj in reader:
24        # Do whatever you want with the trajectories here
Trajectories From TRAJ
1from tracktable.domain.terrestrial import TrajectoryPointReader
2from tracktable_data.data import retrieve
3
4infile = open(retrieve('SampleTrajectories.csv'), 'r')
5trajectories = terrestrial.TrajectoryReader()
6trajectories.input = infile
7
8# Do whatever you want with the trajectories here

Output

Point Output

In order to output both BasePoint and TrajectoryPoint from Tracktable, the appropriate point writer needs to be used. These writers are BasePointWriter and TrajectoryPointWriter, respectively. Each point domain has its own version of the writers. The points can be output to a delimited file or a standard output buffer. Below is an example of outputing TrajectoryPoint to a file. Outputing a BasePoint or using a buffer would have a similar stucture.

1from tracktable.domain.terrestrial import TrajectoryPointWriter
2
3points = []
4# Create some points here
5
6with open('point_output.csv', 'wb') as outfile:
7    writer = TrajectoryPointWriter(outfile) # BasePointWriter(outfile)
8    writer.write(points)

Trajectory Output

Similar to the point output, in order to output a Trajectory from Tracktable the TrajectoryWriter needs to be used. The functionality of the writer is the same as the BasePoint and TrajectoryPoint writers.

1from tracktable.domain.terrestrial import TrajectoryWriter
2
3trajectories = []
4# Create some trajectories here
5
6with open('trajectory_output.csv', 'wb') as outfile: # 'trajectory_output.traj'
7    writer = TrajectoryWriter(outfile)
8    writer.write(trajectory)