diff --git a/src/vapython/va.py b/src/vapython/va.py index 990dc3cf9ef2298d539ccad687f3e625a5670689..df73fa44cff067cdcd9330b65109efebf78c9b35 100644 --- a/src/vapython/va.py +++ b/src/vapython/va.py @@ -590,12 +590,22 @@ class VA(VAInterface): This function connects to a tracking system to track sound sources or receivers. The tracking system can be used to track the position and orientation of sound sources and receivers. + Sources and receivers can be set as "tracked" via the respective `set_tracked_*` functions. + These methods can be used before or after connecting to the tracking system. + Via the `tracker` argument, the tracking system can be selected. Without the IHTATrackingPython package, only the NatNet tracking system is available. Args: server_ip: The IP address of the tracking server. tracker: The tracking system to use. Defaults to `NatNet`. + + Examples: + This will connect to a NatNet tracking system running on the same computer and track a + sound source with the second rigid body. + + >>> va.connect_tracker("127.0.0.1") + >>> va.set_tracked_sound_source(sound_source, 1) """ from vapython.tracking import Tracker @@ -672,6 +682,8 @@ class VA(VAInterface): This function sets a sound source to be tracked by the tracking system. The sound source will be tracked with the given `tracker_id`. + This method can be called before or after connecting to the tracking system. + Args: sound_source_id: The ID of the sound source to track. tracker_id: The ID of the tracker to use. @@ -684,6 +696,8 @@ class VA(VAInterface): This function sets a sound receiver to be tracked by the tracking system. The sound receiver will be tracked with the given `tracker_id`. + This method can be called before or after connecting to the tracking system. + Args: sound_receiver_id: The ID of the sound receiver to track. tracker_id: The ID of the tracker to use. @@ -698,6 +712,8 @@ class VA(VAInterface): The rotation of the torso will influence the HRIR selection. + This method can be called before or after connecting to the tracking system. + Args: sound_receiver_id: The ID of the sound receiver torso to track. tracker_id: The ID of the tracker to use. @@ -710,6 +726,8 @@ class VA(VAInterface): This function sets a real-world sound receiver to be tracked by the tracking system. The real-world sound receiver will be tracked with the given `tracker_id`. + This method can be called before or after connecting to the tracking system. + Args: sound_receiver_id: The ID of the real-world sound receiver to track. tracker_id: The ID of the tracker to use. @@ -724,6 +742,8 @@ class VA(VAInterface): The rotation of the torso will influence the HRIR selection. + This method can be called before or after connecting to the tracking system. + Args: sound_receiver_id: The ID of the real-world sound receiver torso to track. tracker_id: The ID of the tracker to use. @@ -768,6 +788,9 @@ class VA(VAInterface): ) -> None: """Set the offset for a tracked sound receiver. + This can be useful if the origin of the rigid body does not align with the acoustic center. + For example, a tracker mounted on top of a head should still have the acoustic center at ear height. + The orientation offset is applied directly to the orientation of the sound receiver. The position offset is first rotated by the orientation of the sound receiver and then applied. @@ -794,6 +817,8 @@ class VA(VAInterface): ) -> None: """Set the offset for a tracked sound receiver torso. + This can be useful if the origin of the rigid body does not align with the acoustic center. + Args: sound_receiver_id: The ID of the sound receiver torso to set the offset for. @@ -816,6 +841,9 @@ class VA(VAInterface): ) -> None: """Set the offset for a tracked real-world sound receiver. + This can be useful if the origin of the rigid body does not align with the acoustic center. + For example, a tracker mounted on top of a head should still have the acoustic center at ear height. + The orientation offset is applied directly to the orientation of the sound receiver. The position offset is first rotated by the orientation of the sound receiver and then applied. @@ -842,6 +870,8 @@ class VA(VAInterface): ) -> None: """Set the offset for a tracked real-world sound receiver torso. + This can be useful if the origin of the rigid body does not align with the acoustic center. + Args: sound_receiver_id: The ID of the real-world sound receiver torso to set the offset for. orientation_offset: The orientation offset to set.