From cfde4632cd46e42d29a6ad7770b14954df65fad9 Mon Sep 17 00:00:00 2001 From: Pascal Serrarens Date: Tue, 28 Mar 2023 10:44:43 +0200 Subject: [PATCH] Add Custom Tracker documentation --- .../Extensions/Custom/CustomTracker.cs | 80 ++++++++++++++++++- 1 file changed, 78 insertions(+), 2 deletions(-) diff --git a/Runtime/HumanoidControl/Scripts/Extensions/Custom/CustomTracker.cs b/Runtime/HumanoidControl/Scripts/Extensions/Custom/CustomTracker.cs index 81d3e59..00088d0 100644 --- a/Runtime/HumanoidControl/Scripts/Extensions/Custom/CustomTracker.cs +++ b/Runtime/HumanoidControl/Scripts/Extensions/Custom/CustomTracker.cs @@ -6,8 +6,84 @@ namespace Passer.Humanoid { /// /// A tracker wich can be used for custom tracking solutions /// - /// THis tracking option supports custom trackers and sensors for a humanoid. - [System.Serializable] + /// This tracking option supports custom trackers and sensors for a humanoid. + /// We support two types of tracking + /// - using a BodySkeleton + /// - using SensorComponent + /// + /// BodySkeleton + /// ------------ + /// This option is most suited for full body tracking hardware. + /// An example implementation is the PerceptionNeuron extension found in the Humanoid Control Pro edition. + /// For this, you need to implement a class derived from the BodySkeleton class. + /// For the Perception Neuron extension, this new class is Passer::Tracking::PerceptionNeuron. + /// This class should be used for the to the CustomTracker::bodySkeleton parameter. + /// In the new class, you should override the BodySkeleton::start and BodySkeleton::update functions + /// and implement the functionality to correctly start the tracking and retrieving the new body pose. + /// This will ensure that the tracking is started and updated at the right moment. + /// In the update function, you can asssign the tracking result to the correct tracking bones + /// of Humanoid Control. + /// You can retrieve the Humanoid Control TrackedBone using the BodySkeleton::GetBone function. + /// Then you can update the position and/or the rotation of the bone. + /// *Important*: a confidence value between 0 and 1 should also be set for the bone's position and/or rotation. + /// The default confidence is 0 and in that case, the tracking information will not be used. + /// Example of updating one bone: + /// \code + /// protected void UpdateBone(Bone boneId) { + /// TrackedBone bone = GetBone(boneId); + /// if (bone == null) + /// return; + /// + /// // Get Perception Neuron tracking information + /// SensorBone neuronBone = device.GetBone(0, boneId); + /// + /// // Assign the tracking position + /// bone.transform.position = neuronBone.position; + /// // Set the position Confidence + /// bone.positionConfidence = neuronBone.positionConfidence; + /// + /// // Assign the tracking rotation + /// bone.transform.rotation = neuronBone.rotation;; + /// // Set the rotation Confidence + /// bone.rotationConfidence = neuronBone.rotationConfidence; + /// } + /// \endcode + /// + /// SensorComponents + /// ================ + /// This option is most suited for tracking devices which can be mounted on the body. + /// An example implementation is the ViveTracker imnplementation found in the Humanoid Control Pro edition. + /// For this, you need to implement a class derived from the SensorComponent class. + /// For the ViveTracker, this is the Passer::Tracking::ViveTrackerComponent. + /// This class should be used on the Head, Hand, Hips and/or Foot Targets in the CustomSensor::SensorComponent + /// parameter. By selecting the bone in the dropdown, you can set to which bone the device is attached. + /// In the new class, you should override the SensorComponent::StartComponent and SensorComponent::UpdateComponent functions + /// and implement the functionality to correctly start the tracking and retrieve the actual pose of the device. + /// This will ensure that the tracking is started and updated at the right moment. + /// + /// In the overridden SensorUpdate function, you should update the Transform of the SensorComponent. + /// *Important*: a confidence value between 0 and 1 should also be set for the device. + /// The default confidence is 0 and in that case, the tracking information will not be used. + /// Next to that, the status should reflect the current tracking status of the device. + /// Example of updating the device rotation and position: + /// \code + /// public override void UpdateComponent() { + /// if (actionPose.poseIsValid) { + /// transform.localPosition = actionPose.localPosition; + /// transform.localRotation = actionPose.localRotation; + /// + /// status = Tracker.Status.Tracking; + /// positionConfidence = 0.99F; + /// rotationConfidence = 0.99F; + /// } + /// else { + /// status = Tracker.Status.Present; + /// positionConfidence = 0F; + /// rotationConfidence = 0F; + /// } + /// } + /// \endcode +[System.Serializable] public class CustomTracker : HumanoidTracker { /// \copydoc HumanoidTracker::name