trajectopy 5.0.2__tar.gz → 5.0.3__tar.gz

{trajectopy-5.0.2 → trajectopy-5.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: trajectopy
-Version: 5.0.2
+Version: 5.0.3
 Summary: Trajectory Evaluation in Python
 Project-URL: Homepage, https://gereon-t.github.io/trajectopy/
 Project-URL: Documentation, https://gereon-t.github.io/trajectopy/
@@ -62,44 +62,42 @@ Description-Content-Type: text/markdown
 
 ## Installation
 
-Windows app: download `Trajectopy-<version>-setup.exe` from the [latest release](https://github.com/gereon-t/trajectopy/releases/latest) and run it. No Python installation or administrator rights are needed; `.traj` files can then be opened by double-click, and the app reports new versions (Help → Check for Updates).
+**Windows app**: download `Trajectopy-<version>-setup.exe` from the [latest release](https://github.com/gereon-t/trajectopy/releases/latest) and run it. No Python installation or administrator rights are needed; `.traj` files can then be opened by double-click, and the app reports new versions (Help → Check for Updates).
 
-Full version (with GUI):
+**Python package** (Python 3.10 or newer):
 
-```bash
-pip install "trajectopy[gui]"
-```
-
-Python package with plotting (no GUI):
+| Command | Contents |
+| --- | --- |
+| `pip install "trajectopy[gui]"` | Python package and GUI (recommended) |
+| `pip install "trajectopy[plot]"` | Python package with plotting, without the GUI |
+| `pip install trajectopy` | Python package only |
 
-```bash
-pip install "trajectopy[plot]"
-```
+Loading large trajectory files (millions of poses) is several times faster with the `fast` extra, which can be combined with the others: `pip install "trajectopy[gui,fast]"`.
 
-Python package only:
+## Quick Start
 
-```bash
-pip install trajectopy
-```
+```python
+import trajectopy as tpy
 
-Loading large trajectory files (millions of poses) is several times faster with the `fast` extra, which can be combined with the others:
+reference = tpy.Trajectory.from_file("./example_data/KITTI_gt.traj")
+estimate = tpy.Trajectory.from_file("./example_data/KITTI_ORB.traj")
 
-```bash
-pip install "trajectopy[gui,fast]"
+ate_result = tpy.ate(trajectory=estimate, other=reference)  # aligns the estimate first
+print(f"Position ATE: {ate_result.pos_ate:.3f} m")
 ```
 
+Or start the GUI with `trajectopy` (or from the Start menu), drop trajectory files onto it, right-click the ground truth → *Set as Reference*, then right-click another trajectory → *Compare with Reference*.
+
 ## Documentation
 
 <a href="https://gereon-t.github.io/trajectopy/" target="_blank">https://gereon-t.github.io/trajectopy/</a>
 
 ## Key Features
 
-Trajectopy offers a range of features, including:
-
-- __Interactive GUI__: A user-friendly interface that enables seamless interaction with your trajectory data, making it easy to visualize, align, and compare trajectories.
-- __Alignment__: An advanced trajectory alignment algorithm that can be tailored to the specific application and supports a similarity transformation, a leverarm and a time shift estimation.
-- __Comparison__: Absolute and relative trajectory comparison metrics (__ATE and RPE__) that can be computed using various pose-matching methods.
-- __Data Import/Export__: Support for importing and exporting data, ensuring compatibility with your existing workflows.
+- __Interactive GUI__: Load, plot, align and compare trajectories without writing code. Every action explains itself in the context menus, and trajectories can be aligned interactively if an automatic alignment is not possible.
+- __Alignment__: A spatio-temporal least squares alignment that can be tailored to the application: similarity transformation, leverarm and time shift, each of them optional.
+- __Comparison__: Absolute and relative trajectory error (__ATE and RPE__), computed with various pose-matching methods.
+- __Data Import/Export__: ASCII files with configurable columns, time formats and coordinate systems (any EPSG code), and ROS bags.
 - __Fast, Interactive Visualization__: Powered by [pyqtgraph](https://www.pyqtgraph.org/), the same plots are available in the GUI and in Python scripts, stay fluid for large trajectories, and can be exported to PNG, JPG or SVG. Georeferenced trajectories and ATE results can be exported to Google Earth, colored by speed, height or deviations, on the terrain or at their own heights, with playback.
 
 ## Web Application (Docker)

{trajectopy-5.0.2 → trajectopy-5.0.3}/README.md

@@ -22,44 +22,42 @@
 
 ## Installation
 
-Windows app: download `Trajectopy-<version>-setup.exe` from the [latest release](https://github.com/gereon-t/trajectopy/releases/latest) and run it. No Python installation or administrator rights are needed; `.traj` files can then be opened by double-click, and the app reports new versions (Help → Check for Updates).
+**Windows app**: download `Trajectopy-<version>-setup.exe` from the [latest release](https://github.com/gereon-t/trajectopy/releases/latest) and run it. No Python installation or administrator rights are needed; `.traj` files can then be opened by double-click, and the app reports new versions (Help → Check for Updates).
 
-Full version (with GUI):
+**Python package** (Python 3.10 or newer):
 
-```bash
-pip install "trajectopy[gui]"
-```
-
-Python package with plotting (no GUI):
+| Command | Contents |
+| --- | --- |
+| `pip install "trajectopy[gui]"` | Python package and GUI (recommended) |
+| `pip install "trajectopy[plot]"` | Python package with plotting, without the GUI |
+| `pip install trajectopy` | Python package only |
 
-```bash
-pip install "trajectopy[plot]"
-```
+Loading large trajectory files (millions of poses) is several times faster with the `fast` extra, which can be combined with the others: `pip install "trajectopy[gui,fast]"`.
 
-Python package only:
+## Quick Start
 
-```bash
-pip install trajectopy
-```
+```python
+import trajectopy as tpy
 
-Loading large trajectory files (millions of poses) is several times faster with the `fast` extra, which can be combined with the others:
+reference = tpy.Trajectory.from_file("./example_data/KITTI_gt.traj")
+estimate = tpy.Trajectory.from_file("./example_data/KITTI_ORB.traj")
 
-```bash
-pip install "trajectopy[gui,fast]"
+ate_result = tpy.ate(trajectory=estimate, other=reference)  # aligns the estimate first
+print(f"Position ATE: {ate_result.pos_ate:.3f} m")
 ```
 
+Or start the GUI with `trajectopy` (or from the Start menu), drop trajectory files onto it, right-click the ground truth → *Set as Reference*, then right-click another trajectory → *Compare with Reference*.
+
 ## Documentation
 
 <a href="https://gereon-t.github.io/trajectopy/" target="_blank">https://gereon-t.github.io/trajectopy/</a>
 
 ## Key Features
 
-Trajectopy offers a range of features, including:
-
-- __Interactive GUI__: A user-friendly interface that enables seamless interaction with your trajectory data, making it easy to visualize, align, and compare trajectories.
-- __Alignment__: An advanced trajectory alignment algorithm that can be tailored to the specific application and supports a similarity transformation, a leverarm and a time shift estimation.
-- __Comparison__: Absolute and relative trajectory comparison metrics (__ATE and RPE__) that can be computed using various pose-matching methods.
-- __Data Import/Export__: Support for importing and exporting data, ensuring compatibility with your existing workflows.
+- __Interactive GUI__: Load, plot, align and compare trajectories without writing code. Every action explains itself in the context menus, and trajectories can be aligned interactively if an automatic alignment is not possible.
+- __Alignment__: A spatio-temporal least squares alignment that can be tailored to the application: similarity transformation, leverarm and time shift, each of them optional.
+- __Comparison__: Absolute and relative trajectory error (__ATE and RPE__), computed with various pose-matching methods.
+- __Data Import/Export__: ASCII files with configurable columns, time formats and coordinate systems (any EPSG code), and ROS bags.
 - __Fast, Interactive Visualization__: Powered by [pyqtgraph](https://www.pyqtgraph.org/), the same plots are available in the GUI and in Python scripts, stay fluid for large trajectories, and can be exported to PNG, JPG or SVG. Georeferenced trajectories and ATE results can be exported to Google Earth, colored by speed, height or deviations, on the terrain or at their own heights, with playback.
 
 ## Web Application (Docker)

{trajectopy-5.0.2 → trajectopy-5.0.3}/test/test_fast_reading.py

@@ -119,6 +119,36 @@ class TestReadTrajectory(unittest.TestCase):
                 self._assert_same_as_general_reader(text)
 
 
+class TestDatetimeTimeSystems(unittest.TestCase):
+    TEMPLATE = (
+        "#fields t,px,py,pz\n#time_format datetime\n{header}"
+        "2024-01-01 12:00:00.000,0,0,0\n2024-01-01 12:00:00.100,1,0,0\n"
+    )
+    UTC_2024 = 1704110400.0  # 2024-01-01 12:00:00 UTC
+
+    def _timestamps(self, header: str) -> np.ndarray:
+        with tempfile.TemporaryDirectory() as directory:
+            filename = os.path.join(directory, "trajectory.traj")
+            with open(filename, "w", encoding="utf-8") as file:
+                file.write(self.TEMPLATE.format(header=header))
+            return read_trajectory(filename).timestamps
+
+    def test_utc(self):
+        for header_lines in ("", "#datetime_timezone UTC\n"):
+            np.testing.assert_allclose(self._timestamps(header_lines), [self.UTC_2024, self.UTC_2024 + 0.1])
+
+    def test_gps_time_subtracts_the_leap_seconds(self):
+        np.testing.assert_allclose(
+            self._timestamps("#datetime_timezone GPS\n"), [self.UTC_2024 - 18, self.UTC_2024 - 18 + 0.1]
+        )
+
+    def test_other_time_zones_are_read_as_utc_with_a_warning(self):
+        with self.assertLogs(ascii.logger, level="WARNING") as logs:
+            timestamps = self._timestamps("#datetime_timezone Europe/Berlin\n")
+        np.testing.assert_allclose(timestamps, [self.UTC_2024, self.UTC_2024 + 0.1])
+        self.assertTrue(any("Europe/Berlin" in message for message in logs.output))
+
+
 class TestFastExtraHint(unittest.TestCase):
     FILE = "test/data/generated_trajectory.traj"
 

trajectopy-5.0.3/trajectopy/__version__.py

@@ -0,0 +1 @@
+__version__ = "5.0.3"

{trajectopy-5.0.2 → trajectopy-5.0.3}/trajectopy/cli/main.py

@@ -8,13 +8,13 @@ from trajectopy.__version__ import __version__ as VERSION
 
 def main():
     """Main CLI entry point."""
-    parser = argparse.ArgumentParser(description="Trajectopy - Trajectory Evaluation in Python")
+    parser = argparse.ArgumentParser(prog="trajectopy", description="Trajectopy - Trajectory Evaluation in Python")
     parser.add_argument(
         "files",
         nargs="*",
         help="Trajectory (.traj, .bag) or result (.result) files to open (also used when opening files from Windows).",
     )
-    parser.add_argument("--version", "-v", action="store_true")
+    parser.add_argument("--version", "-v", action="store_true", help="Show the version and exit")
     parser.add_argument(
         "--single-thread",
         action="store_true",

{trajectopy-5.0.2 → trajectopy-5.0.3}/trajectopy/core/trajectory.py

@@ -644,7 +644,7 @@ class Trajectory:
 
         write_trajectory(self, filename=filename, mode=mode)
 
-    def to_kml(self, filename: str, precision: float = 1e-6, color: str = "#ff0000", **options) -> None:
+    def to_kml(self, filename: str, precision: float = 1e-6, color: str = "#ff0000", **options: Any) -> None:
         """
         Exports the trajectory to a Google Earth KML file, as a time-stamped track that the time slider of
         Google Earth plays back.

{trajectopy-5.0.2 → trajectopy-5.0.3}/trajectopy/gui/models/entries.py

@@ -141,7 +141,7 @@ class TrajectoryEntry(Entry):
             traj_settings = ProcessingSettings.from_file(str(settings_filename))
         else:
             logger.info(
-                "No settings file found. Settings can be provided by storing a yaml file with the same name in the same directory."
+                "No settings file found. Settings can be provided by storing a JSON file with the same name in the same directory."
             )
             traj_settings = ProcessingSettings()
 

{trajectopy-5.0.2 → trajectopy-5.0.3}/trajectopy/io/ascii.py

@@ -309,19 +309,20 @@ def _parse_datetime(trajectory_data: np.ndarray, time_columns: list[int], header
 
     datetime_strings = np.apply_along_axis(concatenate_strings, 1, trajectory_data[:, time_columns])
 
-    ts_datetime = pd.to_datetime(datetime_strings, format=header_data.datetime_format, utc=True)
+    # Date/time strings are UTC or GPS time; other time zones are not supported (and are read as UTC).
+    time_system = header_data.datetime_timezone.upper()
+    if time_system not in ("UTC", "GPS"):
+        logger.warning(
+            "Unsupported #datetime_timezone '%s': date/time strings must be UTC or GPS time. Reading them as UTC.",
+            header_data.datetime_timezone,
+        )
 
-    if header_data.datetime_timezone.upper() == "GPS":
+    ts_datetime = pd.DatetimeIndex(pd.to_datetime(datetime_strings, format=header_data.datetime_format, utc=True))
+    if time_system == "GPS":
         ts_datetime -= pd.Timedelta(seconds=GPS_LEAP_SECONDS)
-        time_zone = "UTC"
         logger.info("Applied GPS leap seconds.")
-    else:
-        time_zone = header_data.datetime_timezone
-
-    ts_datetime = pd.DatetimeIndex(ts_datetime).tz_convert(tz=time_zone)
-    logger.info("Timezone: %s", time_zone)
 
-    return np.array([dt_i.timestamp() for dt_i in ts_datetime])
+    return np.asarray((ts_datetime - pd.Timestamp(0, tz="UTC")) / pd.Timedelta(seconds=1), dtype=float)
 
 
 def _parse_gps_sow(trajectory_data: np.ndarray, time_columns: list[int], header_data: HeaderData) -> np.ndarray:

{trajectopy-5.0.2 → trajectopy-5.0.3}/trajectopy/results/ate_result.py

@@ -1,5 +1,6 @@
 from dataclasses import dataclass
 from functools import cached_property
+from typing import Any
 
 import numpy as np
 import pandas as pd
@@ -501,7 +502,7 @@ class ATEResult:
 
         return pd.DataFrame(all_data, columns=self.columns)
 
-    def to_kml(self, filename: str, field: str = "position", max_std: float = 3.0, **options) -> None:
+    def to_kml(self, filename: str, field: str = "position", max_std: float = 3.0, **options: Any) -> None:
         """Exports the result to a Google Earth KML file: the trajectory colored by a deviation field, with
         playback in Google Earth's time slider. Requires a trajectory with a known EPSG code.
 

{trajectopy-5.0.2 → trajectopy-5.0.3}/trajectopy-docs/docs/api/index.md

@@ -25,6 +25,7 @@ Welcome to the Trajectopy API reference. This section provides detailed document
 - **[Trajectory I/O](io/trajectory_io.md)** - Read and write trajectories (ASCII)
 - **[Results I/O](io/results_io.md)** - Read and write ATE/RPE/alignment results and parameters
 - **[Google Earth (KML)](io/kml.md)** - Export trajectories and ATE results to Google Earth
+- **[ROS Bags](io/rosbag.md)** - Read trajectories from ROS1 bag files
 
 ## Results
 

trajectopy-5.0.3/trajectopy-docs/docs/api/io/rosbag.md

@@ -0,0 +1,3 @@
+# ROS Bags
+
+::: trajectopy.io.rosbag

trajectopy-5.0.3/trajectopy-docs/docs/file_formats.md

@@ -0,0 +1,204 @@
+# File Formats
+
+Trajectopy reads trajectories from:
+
+- **ASCII files** (`.traj`, `.txt`, `.csv`, …): one pose per line; a header describes the columns.
+- **ROS1 bag files** (`.bag`): `geometry_msgs/PoseStamped` and `geometry_msgs/PointStamped` messages.
+
+## ASCII Files
+
+### Structure
+
+Each line holds one pose. Lines starting with `#` are header lines, which describe how the data is interpreted.
+Without a header, the columns are `t,px,py,pz,qx,qy,qz,qw` (time, position, quaternion), separated by commas:
+
+```
+1000.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0
+1000.1,0.1,0.0,0.0,0.0,0.0,0.0,1.0
+1000.2,0.2,0.0,0.0,0.0,0.0,0.0,1.0
+```
+
+With a header:
+
+```
+#name MyTrajectory
+#epsg 25832
+#fields t,px,py,pz,qx,qy,qz,qw
+1000.0,364000.0,5621000.0,60.0,0.0,0.0,0.0,1.0
+1000.1,364000.1,5621000.0,60.0,0.0,0.0,0.0,1.0
+```
+
+### Header Lines
+
+| Header | Description | Default | Options |
+|--------|-------------|---------|---------|
+| `#name` | Display name | `Trajectory` | Any string |
+| `#epsg` | EPSG code of the positions | `0` | Any EPSG code; `0` = local coordinates without a known datum |
+| `#fields` | Meaning of the columns | `t,px,py,pz,qx,qy,qz,qw` | Comma-separated [field names](#field-names) |
+| `#delimiter` | Column separator, in quotes | `','` | Any single character, e.g. `#delimiter ';'` |
+| `#nframe` | Navigation frame of the data | `enu` | Order of east, north and up/down, e.g. `enu`, `ned`, `neu` |
+| `#rot_unit` | Unit of Euler angles | `rad` | `rad`, `deg` |
+| `#euler_rot_seq` | Axis sequence of Euler angles | `xyz` | Up to 3 of `x`, `y`, `z` for extrinsic or `X`, `Y`, `Z` for intrinsic rotations (not mixed) |
+| `#time_format` | Format of the time column(s) | `unix` | `unix`, `datetime`, `gps_sow` |
+| `#time_offset` | Offset in seconds added to all timestamps | `0.0` | Any number |
+| `#datetime_format` | Format of date/time strings | `%Y-%m-%d %H:%M:%S.%f` | [strftime format](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) |
+| `#datetime_timezone` | Time system of date/time strings | `UTC` | `UTC` or `GPS` |
+| `#gps_week` | GPS week of `gps_sow` timestamps | `0` | Integer |
+| `#sorting` | Order of the poses | `time` | `time`, `path_length` (or `arc_length`) |
+
+Notes:
+
+- **Delimiter**: the character must be in quotes; without them, the line is ignored and a comma is used.
+  Whitespace-separated files (spaces or tabs) are detected automatically and need no `#delimiter` line.
+- **Navigation frame**: positions, velocities and orientations are converted to ENU. Positions are only
+  converted if `#epsg` is `0`; with an EPSG code, their axes are defined by the coordinate system.
+- **GPS time**: `gps_sow` timestamps are seconds of the GPS week given by `#gps_week`; they are converted to UTC
+  (including leap seconds). `#datetime_timezone GPS` does the same for date/time strings.
+- **Time systems**: date/time strings must be UTC or GPS time; local time zones are not supported (other values
+  are read as UTC, with a warning). A constant offset can be corrected with `#time_offset`.
+- Header lines may also appear after the data (e.g. comments), but files with all header lines at the top load
+  faster.
+
+### Field Names
+
+| Field | Description | Can repeat? |
+|-------|-------------|-------------|
+| `t` | Time | Yes, for date and time in separate columns (`#time_format datetime`) |
+| `l` | Path length (arc length) in meters | No |
+| `px`, `py`, `pz` | Position (in the order of the coordinate system, e.g. latitude, longitude, height for EPSG 4326) | No |
+| `qx`, `qy`, `qz`, `qw` | Orientation as quaternion | No |
+| `ex`, `ey`, `ez` | Orientation as Euler angles (roll, pitch, yaw; see `#rot_unit` and `#euler_rot_seq`) | No |
+| `vx`, `vy`, `vz` | Velocity in meters per second | No |
+| `-` | Column that is not used | Yes |
+
+Only `px`, `py` and `pz` are required. Without time column, the line number is used as timestamp; without
+orientation, the trajectory has positions only (no rotation deviations, no leverarm estimation). If both
+quaternions and Euler angles are given, the quaternions are used.
+
+### Examples
+
+**Positions only**
+
+```
+#name PositionOnly
+#fields t,px,py,pz
+1000.0,0.0,0.0,0.0
+1000.1,0.1,0.0,0.0
+1000.2,0.2,0.0,0.0
+```
+
+**Euler angles in degrees**
+
+```
+#name EulerTrajectory
+#fields t,px,py,pz,ex,ey,ez
+#rot_unit deg
+1000.0,0.0,0.0,0.0,0.0,0.0,0.0
+1000.1,0.1,0.0,0.0,0.0,0.0,5.0
+```
+
+**Space-separated, with unused columns**
+
+```
+#name SpaceSeparated
+#fields t,-,-,px,py,pz
+1000.0 17 ok 0.0 0.0 0.0
+1000.1 17 ok 0.1 0.0 0.0
+```
+
+**Geographic coordinates (latitude, longitude, ellipsoidal height)**
+
+```
+#name GNSS
+#epsg 4979
+#fields t,px,py,pz
+1000.0,50.7374,7.0982,120.5
+1000.1,50.7375,7.0983,121.2
+```
+
+**Date and time strings**
+
+```
+#name DatetimeTrajectory
+#fields t,px,py,pz,qx,qy,qz,qw
+#time_format datetime
+#datetime_format %Y-%m-%d %H:%M:%S.%f
+#datetime_timezone UTC
+2024-01-01 12:00:00.000,0.0,0.0,0.0,0.0,0.0,0.0,1.0
+2024-01-01 12:00:00.100,0.1,0.0,0.0,0.0,0.0,0.0,1.0
+```
+
+Date and time can also be in separate columns: `#fields t,t,px,py,pz` (they are joined with a space).
+
+**GPS time (seconds of week), NED frame, semicolon-separated**
+
+```
+#name GPSTime
+#fields t,px,py,pz,qx,qy,qz,qw
+#delimiter ';'
+#nframe ned
+#time_format gps_sow
+#gps_week 2250
+345600.0;0.0;0.0;0.0;0.0;0.0;0.0;1.0
+345600.1;0.1;0.0;0.0;0.0;0.0;0.0;1.0
+```
+
+### Large Files
+
+Files with millions of poses load several times faster with the optional pyarrow reader:
+`pip install "trajectopy[fast]"`. It is used automatically when installed, for files without date/time strings.
+
+## ROS Bags
+
+ROS1 bag files (`.bag`) can be opened in the GUI like ASCII files, or read in Python:
+
+```python
+from trajectopy.io.rosbag import trajectories_from_rosbag
+
+trajectories = trajectories_from_rosbag("recording.bag")
+```
+
+Every topic with `geometry_msgs/PoseStamped` (position and orientation) or `geometry_msgs/PointStamped`
+(position only) messages becomes one trajectory, named after the topic; the timestamps are taken from the message
+headers. Messages of other types are skipped.
+
+## Files Written by Trajectopy
+
+- **Trajectories** (`Trajectory.to_file`, *Export…* in the GUI) are ASCII files as described above, with the
+  fields `t,l,px,py,pz,qx,qy,qz,qw,vx,vy,vz` (without `qx`…`qw` for trajectories without orientation).
+- **Results** (`.result`): ATE, RPE and alignment results (`ATEResult.to_file`, `RPEResult.to_file`,
+  `AlignmentResult.to_file`). They are text files with a header, too, and can be opened in the GUI.
+- **Settings** (`.json`): [processing settings](settings.md#processing-settings) and
+  [plot settings](settings.md#plot-settings).
+- **Sessions** (GUI): a folder with all trajectories, results and settings, see
+  [Using the GUI](user_guide.md#menu-bar).
+
+## Creating Trajectories in Python
+
+```python
+import numpy as np
+import trajectopy as tpy
+
+timestamps = np.arange(0, 10, 0.1)
+positions = np.column_stack(
+    [
+        timestamps,  # x increases with time
+        np.sin(timestamps),  # y is sinusoidal
+        np.zeros_like(timestamps),  # z is zero
+    ]
+)
+quaternions = np.tile([0, 0, 0, 1], (len(timestamps), 1))  # identity (x, y, z, w)
+
+trajectory = tpy.Trajectory.from_arrays(
+    xyz=positions,
+    quat=quaternions,  # or rpy=... (roll, pitch, yaw in radians)
+    timestamps=timestamps,
+    name="CustomTrajectory",
+)
+trajectory.to_file("custom.traj")
+```
+
+## See Also
+
+- [User Guide](user_guide.md): loading files in Python and the GUI
+- [API Reference](api/io/trajectory_io.md): reading and writing trajectories

trajectopy-5.0.3/trajectopy-docs/docs/index.md

@@ -0,0 +1,149 @@
+<div align="center">
+    <h1>Trajectopy - Trajectory Evaluation in Python</h1>
+    <a href="https://github.com/gereon-t/trajectopy/releases"><img src="https://img.shields.io/github/v/release/gereon-t/trajectopy?label=version" /></a>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" /></a>
+    <a href="https://github.com/gereon-t/trajectopy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gereon-t/trajectopy" /></a>
+    <a href="https://github.com/astral-sh/ruff"><img alt="Code style: ruff" src="https://img.shields.io/badge/code%20style-ruff-000000.svg"></a>
+    <br />
+    <a href="https://github.com/gereon-t/trajectopy"><img src="https://img.shields.io/badge/Windows-0078D6?st&logo=windows&logoColor=white" /></a>
+    <a href="https://github.com/gereon-t/trajectopy"><img src="https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black" /></a>
+    <a href="https://github.com/gereon-t/trajectopy"><img src="https://img.shields.io/badge/mac%20os-000000?&logo=apple&logoColor=white" /></a>
+
+<h4>Trajectopy is a Python package with an optional graphical user interface for empirical trajectory evaluation. </h4>
+
+<p align="center">
+  <img style="border-radius: 10px;" src="https://raw.githubusercontent.com/gereon-t/trajectopy/main/.images/trajectopy_gif_low_quality.gif">
+</p>
+
+</div>
+
+
+## Key Features
+
+- __Interactive GUI__: Load, plot, align and compare trajectories without writing code. Every action explains
+  itself in the context menus, and trajectories can be aligned interactively if an automatic alignment is not possible.
+- __Alignment__: A spatio-temporal least squares alignment that can be tailored to the application: similarity
+  transformation, leverarm and time shift, each of them optional.
+- __Comparison__: Absolute and relative trajectory error (__ATE and RPE__), computed with various pose-matching methods.
+- __Data Import/Export__: ASCII files with configurable columns, time formats and coordinate systems
+  (any EPSG code), and ROS bags.
+- __Fast, Interactive Visualization__: Powered by [pyqtgraph](https://www.pyqtgraph.org/), the same plots are
+  available in the GUI and in Python scripts, stay fluid for large trajectories, and can be exported to PNG, JPG
+  or SVG. Georeferenced trajectories and ATE results can be exported to Google Earth, colored by speed, height or
+  deviations, on the terrain or at their own heights, with playback.
+
+## Installation
+
+### Windows App
+
+Download `Trajectopy-<version>-setup.exe` from the [latest release](https://github.com/gereon-t/trajectopy/releases/latest)
+and run it. No Python installation or administrator rights are needed. The installer adds Trajectopy to the Start
+menu and, optionally, opens `.traj` files with it on double-click. The app reports new versions (Help → Check for
+Updates); installing a newer version over an existing one updates it.
+
+As the installer is not signed, Windows SmartScreen may warn about an unknown publisher: choose
+*More info → Run anyway*.
+
+### Python Package
+
+| Command | Contents |
+| --- | --- |
+| `pip install "trajectopy[gui]"` | Python package and GUI (recommended) |
+| `pip install "trajectopy[plot]"` | Python package with plotting, without the GUI |
+| `pip install trajectopy` | Python package only |
+
+Trajectopy requires Python 3.10 or newer.
+
+**Faster loading of large files**: trajectory files with millions of poses load several times faster with the
+optional `fast` extra, which installs [pyarrow](https://arrow.apache.org/docs/python/) for reading. It can be
+combined with the other extras:
+
+```console
+pip install "trajectopy[gui,fast]"
+```
+
+## Quick Start
+
+### Python
+
+Load two trajectories and compute the absolute and relative trajectory error. The example files are in the
+[`example_data`](https://github.com/gereon-t/trajectopy/tree/main/example_data) folder of the repository.
+
+```python
+import trajectopy as tpy
+
+reference = tpy.Trajectory.from_file("./example_data/KITTI_gt.traj")
+estimate = tpy.Trajectory.from_file("./example_data/KITTI_ORB.traj")
+
+# ATE: the estimate is aligned to the reference first (similarity transformation)
+ate_result = tpy.ate(trajectory=estimate, other=reference)
+print(f"Position ATE: {ate_result.pos_ate:.3f} m")
+
+# RPE: drift per 100 m to 800 m (see the relative comparison settings)
+rpe_result = tpy.rpe(trajectory=estimate, other=reference)
+print(f"Position RPE: {rpe_result.pos_rpe:.3f} {rpe_result.pos_drift_unit}")
+```
+
+The [User Guide](user_guide.md) covers alignment, evaluation, plots and the GUI in detail.
+
+### GUI
+
+Start the Windows app from the Start menu, or run:
+
+```console
+trajectopy
+```
+
+Drop trajectory files onto the trajectory table, right-click the ground truth and choose *Set as Reference*,
+then right-click another trajectory and choose *Compare with Reference*. See [Using the GUI](user_guide.md#6-using-the-gui).
+
+## Command Line
+
+```console
+trajectopy [-h] [--version] [--single-thread] [--plot-settings PLOT_SETTINGS] [files ...]
+```
+
+| Argument | Description |
+| --- | --- |
+| `files` | Trajectory (`.traj`, `.bag`) or result (`.result`) files to open at start. |
+| `--version`, `-v` | Show the version and exit. |
+| `--single-thread` | Process in the GUI thread instead of a background thread, e.g. for debugging. The GUI does not respond while processing. |
+| `--plot-settings PLOT_SETTINGS` | JSON file with [plot settings](settings.md#plot-settings); settings missing in the file keep their default values. |
+| `-h`, `--help` | Show the help and exit. |
+
+Examples:
+
+```console
+trajectopy ground_truth.traj slam.traj
+trajectopy --plot-settings my_session/plot_settings.json
+```
+
+A session saved from the GUI contains its plot settings in `plot_settings.json`.
+
+## Citation
+
+If you use Trajectopy for academic work, please cite our [paper](https://www.degruyter.com/document/doi/10.1515/jag-2024-0040/html):
+
+```bibtex
+@article{Tombrink2024,
+  title = {Spatio-temporal trajectory alignment for trajectory evaluation},
+  author = {Gereon Tombrink and Ansgar Dreier and Lasse Klingbeil and Heiner Kuhlmann},
+  journal = {Journal of Applied Geodesy},
+  year = {2024},
+  doi = {10.1515/jag-2024-0040},
+  url = {https://doi.org/10.1515/jag-2024-0040},
+  codeurl = {https://github.com/gereon-t/trajectopy}
+}
+```
+
+## License
+
+Trajectopy is released under the GNU General Public License v3.0.
+
+## Contributing
+
+Contributions are welcome! Please see our [GitHub repository](https://github.com/gereon-t/trajectopy) for details.
+
+---
+
+*Developed at the Institute of Geodesy and Geoinformation, University of Bonn*