Tracktable: moving object trajectory analysis in C++ and Python
This is the release that was supposed to be Tracktable 1.7.0... but with the release bugs fixed. The release notes below are a combination of the things we fixed for 1.7.1 and what we added for 1.7.0.
Linux wheel-building scripts will now attempt to build Tracktable for all versions of CPython newer than 3.6 that are available in the manylinux wheel. This improves on previous work where we used a hardcoded and oft-duplicated list of versions to build.
The manylinux tag is now a CMake argument. We will continue to default to manylinux2014 for the moment but when it comes time to change that we will only need to update it in one place.
We now control wheel building with setup.cfg and pyproject.toml
instead of the outdated python setup-generic.py. This puts our
build process on much sounder footing and will work better with
the conda-forge build process.
The function libraries used by the MacOS CI scripts and wheel-building scripts have been consolidated to remove duplication.
Large files in tracktable-docs and tracktable-data have been moved into Git LFS.
Maps in Folium can now be created with the attr and crs
parameters. The attr argument is used to pass an attribution string
for custom tile sets. The crs argument names a coordinate transform
to project geographical points into pixel coordinates and back. The
functions tracktable.render.render_trajectories.render_trajectories()
and tracktable.render.render_heatmap.render_heatmap() both support these
new arguments.
Trajectory maps in Folium can be animated. See the arguments animate,
anim_display_update_interval, anim_trail_duration, and use_markers
in tracktable.render.render_trajectories.render_trajectories().
New function tracktable.rw.load.load_trajectories() that will load a
.traj, .csv, or .tsv file and assemble points into trajectories.
An optional flag will cause it to return points instead of trajectories.
Examples that load trajectories or points have been updated to use this
feature.
Sea ports and airports can be rendered into maps for both the Cartopy and Folium back ends.
Docs and data have been separated out into their own repositories
implemented as submodules. Note that you will need to git clone --recursive
when cloning the source code.
There is a compile error caused by a ternary expression inside a constexpr in tracktable/ThirdParty/catch2.hpp. This is an error because of some new rules in GCC. The fix is to eliminate the ternary expression and just set the stack size for Catch2 to 32K.
We now include boost-cpp in the Anaconda dependencies for our build
and runtime environments. In some situations, compiled libraries in
Boost that we rely upon were only present in that package.
Fixed a typo in setup-generic.py that broke wheel building.
Switched to libmamba solver on ReadTheDocs. Without it, our builds
time out while waiting for conda install to decide what packages
it wants.
Fixed an unbound variable error in build_osx_wheels.sh when a
wheel output directory was explicitly specified.
Fixed a problem that led to great-circle fitting returning numerically incorrect answers.
Removed deprecated uses of std::unary_function<>. This was deprecated
in C++11 and removed entirely in C++17.
We identified and fixed a problem with the I/O library that could cause a buffer overflow if the user opened a file containing UTF-8 data in Python in text mode and then passed it to one of Tracktable's loaders.
Map scale bars were being rendered incorrectly in static images under map projections that did not use geodetic coordinates (longitude/ latitude) as their native coordinate system.
Tests for C++ point generators and great circle estimation were failing because points did not initialize their coordinates by default. Fixing this results in a very minor slowdown.
Setting a point property's value to None no longer crashes the interpreter.
DeprecatedDeclaration.h was not being installed when the user called
make install.
The documentation for tracktable.rw.load.load_trajectories() implies
that it takes a file-like object as its input. It does not -- it takes
a string containing a filename.
Documentation for tracktable.rw is not picking up the module contents.
There are a few files in the wheel (Jupyter notebooks and response files) that really don't belong there. They are harmless but should be removed.
The data generators in tracktable.examples.data_generators have now moved
to tracktable.data_generators.
Movies can be rendered directly from tracktable.render.render_movie.render_trajectory_movie
now. This subsumes the code that used to be in the
movie_from_trajectories example.
Jupyter notebook tutorials are built locally and stored in a separate repository (tracktable-docs) so that we no longer run into the CPU usage limits when uploading to ReadTheDocs.
The latest release branch in our repository is now called main,
not master.
Sample data has been moved into a separate repository (tracktable-data) to help keep the Tracktable repository itself small(er).
We no longer officially support Python 3.6 or 3.7. Python 3.6 stopped getting security updates in December 2021. Python 3.7 stopped getting security updates in June 2023.
Having said that, we have not yet made any changes to the code that actually require Python 3.8 or newer.
If you need to build and run Tracktable 1.7 in an environment where you
absolutely cannot update to a more recent Python version, contact us.
We sympathize -- we have plenty of experience with such environments --
and we'll work with you to get you up and running.
We are now building wheels for Python versions up through 3.11. On Linux, we build and upload wheels to PyPI for Python versions 3.6 through 3.11. On Windows and MacOS (Intel), we build wheels for Python 3.8 through 3.11. On MacOS (Apple Silicon/arm64), we build wheels for Python 3.10 and 3.11.
We've moved all of our Linux build infrastructure to Docker containers
for easier management. This also helps us build wheels with the manylinux
standard that are usable on most common distributions. Along the way,
we've integrated test coverage and code linting into our CI pipeline.
We're planning to do something similar for our Windows builds now that Docker on Windows hosts can run containers with the Windows kernel.
MacOS build and test procedures are still run via shell scripts due to the lack of container support in the MacOS kernel.
The packaging code in this release has fatal flaws that result in wheels that can't be imported. Don't use it. Use 1.7.1 (coming very soon) instead.
Welcome back!
Most of the work in this release is in the build and test infrastructure to make our development practices more sustainable. We've added the following user-facing features:
Maps in Folium can now be created with the attr and crs
parameters. The attr argument is used to pass an attribution string
for custom tile sets. The crs argument names a coordinate transform
to project geographical points into pixel coordinates and back. The
functions tracktable.render.render_trajectories.render_trajectories()
and tracktable.render.render_heatmap.render_heatmap() both support these
new arguments.
Trajectory maps in Folium can be animated. See the arguments animate,
anim_display_update_interval, anim_trail_duration, and use_markers
in tracktable.render.render_trajectories.render_trajectories().
New function tracktable.rw.load.load_trajectories() that will load a
.traj, .csv, or .tsv file and assemble points into trajectories.
An optional flag will cause it to return points instead of trajectories.
Examples that load trajectories or points have been updated to use this
feature.
Sea ports and airports can be rendered into maps for both the Cartopy and Folium back ends.
Docs and data have been separated out into their own repositories
implemented as submodules. Note that you will need to git clone --recursive
when cloning the source code. The tracktable-data package should be installed
as a dependency when you install with pip or from conda-forge.
Full details are available in the https://tracktable.readthedocs.io.
Here's what's in this release:
tracktable-data wheel as welltracktable-1.7.0-docs.tar.gz (or .tar.bz2 or .zip). The file tracktable-1.7.0-src-docs.tar.gz is NOT the user-facing documentation.tracktable-1.7.0-src-everything.tar.gz (or .tar.bz2 or .zip)tracktable-1.7.0-src.tar.gz (or .tar.bz2 or .zip)tracktable-1.7.0-src-docs.tar.gz (or .tar.bz2 or .zip)tracktable-1.7.0-data.tar.gz (or .tar.bz2 or .zip)We expect the source to change much more quickly than the sample data and documentation, which is why we split the repositories.
For any questions, please write to tracktable-questions at sandia dot gov or open an issue in this repository.
This release contains a patch for missing modules in tracktable.examples, see release 1.6.0 for the full release notes.
This release contains a patch for an incorrect import in tracktable.analysis, see release 1.6.0 for the full release notes.
NOTE:
This release includes a hotfix for a download error in Cartopy. As soon as the Cartopy team is able to fix this in a new release we will update our version requirements and remove the hotfix. For more information about the underlying problem, see https://github.com/nvkelso/natural-earth-vector/issues/581.
This release includes major API changes:
Render module (tracktable.render) has been refactored to abstract away
details of the back end
Analysis module (tracktable.analysis) has been split into Applications
(tracktable.applications) and Algorithms (tracktable.algorithms).
Bindings from the Analysis module are still in place with deprecation
warnings and will be removed in release 1.8.
The Applications module contains functions for prediction, anomaly detection, clustering, and "boxiness" (how close a trajectory is to a perfect square). We will be refining and updating these modules in the next few releases.
We've added better debugging support for our import process. The common
error about being unable to import _core_types has been augmented by
tests to find out exactly where in the import chain things are going wrong.
This release also includes revamped Python tutorials and demos which should be easier to follow
and try out for yourself! Find them in the code at ...tracktable/Python/tracktable/examples
and on ReadTheDocs at https://tracktable.readthedocs.io/en/latest/examples/examples.html.
This release includes major updates to the documentation. The Python and C++ user guides have been overhauled. Example Jupyter notebooks are now included in the documentation.
We are also building wheels for Python 3.9 as of this release. Tracktable 1.6, due in summer 2021, will be the last version to support Python 3.5. (Python 3.5 has reached the end of its support window. See https://www.python.org/downloads/release/python-3510/ for details.)
See trajectory/tracktable!211 for detailed changes.