Trajdata

This version brings with it a major overhaul of how tensors/arrays with state information are treated, a few extra functionalities related to lane querying, improvements to visualization (stay tuned for more improvements along this direction in the future), and bugfixes. See the notes below for more details.

* The agent state information returned in the Agent/SceneBatch or Agent/SceneBatchElement objects now includes z information for all datasets. This is required for association with VectorMap elements which include z information.
* Instead of state information being stored as simple torch.Tensor or np.ndarray objects in Agent/SceneBatch or Agent/SceneBatchElement objects, they are stored as a new StateTensor or StateArray objects. These types subclass Tensor or ndarray, so downstream pytorch model should work as expected. However, these subclasses allow writing code to access state-elements semantically, rather than relying on say, the x velocity appearing at index 3. This allows downstream code to be written in a more readable manner, and in a way that is robust to future changes in state order, e.g. if we need to add more 3d information, or add properties like heading rate, etc. Furthermore, moving forward, we can write general purpose state transformation utilities that operate on these State objects. See examples/state_example.py for an example.
* Added a get_current_lane function to VectorMap which takes in xyzh of an agent, and returns a set of lanes that the agent is likely to be on. (Unlike get_closest_lane, this factors in the heading of the agent as well. Updated the examples/lane_query_example.py to use this function. The results are much better in intersections, where there are many overlapping lanes.
* Added arguments to UnifiedDataset that allow the user to specify the desired state elements upon its construction (e.g., which derivatives do they want? do they want heading in sin/cos format or not?)
* Improvements to visualization.
* Bugfixes and additional tests for StateTensor propagation across a few different computations.

This release adds a couple new features as well as bugfixes and preparation for the next big release (v1.2.0, stay tuned!).

Namely, we've added:
* AgentBatch-SceneBatch transform utilities.
* Batch filtering.
* Agent metadata.
* xyz-based lane distance querying.
* Ability to query for the _unique_ set of closest lanes.
* Bugfixes related to torch distributed use, simulation arguments, and neighbor type order.

Lots of new features and internal changes in this version!

Namely, we've implemented:
* Initial (beta) support for nuPlan! So far, we've only really tested the nuPlan mini split and are waiting for the devkit to be released more widely (e.g., on PyPI) before supporting the rest of the dataset.
* A new `VectorMap` object which provides users a unified interface to dataset maps (if available). It supports efficient geometric querying for nearest lanes, accessing raw polylines and polygons, traffic light status (beta, and only currently implemented for nuPlan), as well as basic utilities like interpolation and projection. We also provide new example scripts (`examples/{map_api, simple_map_api, lane_query}_example.py`) demonstrating some functions of the new vector map API.
* **NOTE:** The way lane querying is done will change slightly in the future, currently heading is taken as an input but this will be removed explicitly in the future.
* **NOTE:** While many of the typical map elements from AV datasets are included (i.e., road lanes, driveable areas, pedestrian crosswalks and walkways), not all are. Keep an eye out for future updates which address this and expand upon our map format!
* A `MapAPI` object that manages and creates/loads `VectorMap` objects.
* Changes to some of the `UnifiedDataset` init arguments to distinguish between vector map parameters and rasterized map parameters.
* The (beta) capability to store and load already-computed batch elements for significantly faster loading later. See `examples/cache_and_filter_example.py` for an example of its usage.
* **NOTE:** While we provide an initial implementation of this functionality, it is not very efficient right now and uses a lot of space on disk. Look out for future updates that improve upon this!
* Internal code refactors to put utilities and other classes in more sensible locations (e.g., now all utilities live within `utils/`, they were more spread out before).
* Added utilities (and associated tests) for converting between batch types.
* Added tests for a few map functions (to be expanded).

**If upgrading from a previous version, please make sure to delete your unified data cache and recreate it using this latest version of trajdata.**

The extra features are:
* Enabling the limiting of the maximum number of neighbors included in an agent-centric batch element.
* Enabling the returning of only ego-centric batches.

The hotfix refers to bringing back the original format of datasets' map rasterizations (prior to v1.0.7 you could choose between having RGB channels or semantic channels, e.g., nuScenes has 7, however v1.0.7 inadvertently removed the latter and so this hotfix brings it back). Users can request rasterized maps in a dataset's original format by adding `"original_format": True` to the `map_params` dict. By default, it is `False`.

**NOTE:** Changing the desired format of rasterized maps necessitates re-caching maps in the unified data cache.

Here's a summary of the changes (in no particular order):

* The ability to specify padding direction has been added (whether historical agent states should be padded on the left or right).
* A standardized map format has been added and is now being used (VectorizedMap) based on protobufs for efficient storage.
* Accordingly, map extraction functions have been added to the nuScenes and Lyft Level 5 interfaces.
* Speedups related to data standardization in the default DataFrameCache.
* Added timestep frequency downsampling (previously only upsampling was implemented).
* Standardized the map handling of datasets with no maps (empty patches with a given fill value will be returned).
* Added the ability to add extra tensors to batch elements, see `examples/custom_batch_data.py` for examples.
* Allow floating point map resolutions.
* Added `scene_id` to batches.
* Added argument `only_predict` to `UnifiedDataset` which filters down the data index (i.e., which agents to predict) without also filtering agents from the scene.
* Speedups to dataloading, owing to improvements in the `UnifiedDataset`'s underlying data index implementation.
* Changed nuScenes splits to better match the official splits from the dataset (closer to the prediction challenge, but not filtering all the way down to particular instance and sample tokens).
* Added the ability to add agents on the fly during simulation.

**NOTE**: If upgrading from a previous version, please make sure to delete your unified data cache and recreate it using this latest version of trajdata.

This release brings significant speed ups to timestep interpolation, some variable/method refactoring, as well as slight changes to the default cache structure.

**Note:** Upgrading to this version from a previous version necessitates rebuilding your data cache! Doing this will (hopefully) become less necessary as the code stabilizes.