Johnliu/optitrack autonomy

[JohnYanxinLiu]

What features did you add and/or bugs did you address?

• GitHub issue:

• Adds native OptiTrack motion capture integration to AirStack via the NatNet SDK.
  The natnet_ros2 package receives rigid body pose data from an external Motive PC
  over NatNet UDP and publishes into the AirStack perception layer as standard ROS 2
  PoseStamped / PoseWithCovarianceStamped topics, with an optional MAVROS bridge
  for PX4 external pose feedback.

  Also included: unit testing infrastructure improvements — pytest registration fixes
  for lidar_point_cloud_filter, a YAML-driven colcon test manifest
  (tests/colcon_unit_test_packages.yaml), and ~55 C++ gtests + 7 Python unit tests
  for natnet logic.

How did you implement it?

• C++ NatNet node (natnet_ros2_node.cpp): connects to Motive via the NatNet SDK,
  registers a frame callback that decodes rigid body poses, and publishes them namespaced
  under /{ROBOT_NAME}/perception/optitrack/{body_name}.

• Python vision pose converter (vision_pose_converter_node.py): subscribes to the
  raw optitrack pose and re-publishes as /{ROBOT_NAME}/mavros/vision_pose/pose with
  canonical quaternion normalization for PX4.

• Opt-in by default: LAUNCH_NATNET defaults to false in docker-compose.yaml
  (LAUNCH_NATNET=${LAUNCH_NATNET:-false}). Set LAUNCH_NATNET=true in .env to
  activate. If true but the SDK was not installed, the launch file raises a
  RuntimeError (fail-hard rather than silently skip).

• Conditional build: CMakeLists.txt detects the SDK at configure time. If absent,
  the natnet_ros2_node executable is skipped with a warning — the package still builds
  cleanly for CI without the SDK.

• SDK licensing: The OptiTrack NatNet SDK is proprietary and not redistributed.
  Users install it locally via airstack setup (explicit license acceptance). AirStack
  remains fully open-source.

• LD_LIBRARY_PATH: An ament env-hook (natnet_library_path.dsv.in) adds the SDK
  .so to LD_LIBRARY_PATH on sws so no manual path configuration is needed.

• Unit test isolation: C++ logic (frame decoding, covariance matrix construction,
  topic name building) is separated into a thin adapter class so it can be tested
  without the real SDK or a live ROS node. Tests live in
  robot/ros_ws/src/perception/natnet_ros2/test/test_natnet_logic.cpp.

• YAML test manifest: tests/colcon_unit_test_packages.yaml lists which packages
  are gated under colcon test in CI. This replaces a hardcoded list in
  test_build_packages.py and makes it easy to add new packages without touching the
  test harness.

How do you run and use it?

• What commands and button presses do you use to manually launch the stack to use your new feature?
  To install the NatNet SDK, run
  airstack setup

You can launch airstack with NatNet enabled:
AUTOLAUNCH=true; LAUNCH_NATNET=true; airstack up

For now, this will only launch the natnet application without connecting to any server. Soon, an Isaac-Sim emulator will be implemented to give this more confidence. For now, NatNet is not launched by defualt.

• Write a detailed procedure with EXACT BASH COMMANDS so that another maintainer can replicate and understand the benefits of your feature, and reproduce the videos and images you added above.
  (Listed above)

Testing with PyTest

• What pytests did you add to ensure the feature is reliable and robust? What metrics are used?
  Unit tests for lidar_filter_cloud are reorganized, and unit tests regarding the helper functions and coordinate framing for optitrack are added.

• What's the exact command to run the pytests that test your feature? i.e. airstack test -m ...
  To test python-based unit tests, run airstack test -m unit -v
  To run C++ unit tests and building, run airstack test -m build_packages -k test_colcon_test_robot -v

• What are the expected results of the tests? What should a maintainer look at to understand whether the test succeeded?
  All tests should pass.

Documentation

• Was mkdocs.yml updated? (y/n)
  y

• Do the docs have sufficient scope such that a newcomer can easily reproduce and use your feature?
  yes, the structure of the unit tests are decided and documented in the development procedure. SKILLS directory is updated with templates for new agents to contribute.

• Is there sufficient visual media?
  N/A

Versioning

• Did you make sure to bump the version number in the .env file according to semantic versioning?
  yes