Mt2dTrackData / Mt2dTrack / MtData Manual

Table of Contents

• About
• Access
• Access Tracks
• Access Track Data
• Position Data
• Further Reading

About

A Mt2dTrackData object stores information on 2D tracks created with the Motion Tracker object. It provides access to Mt2dTrack objects that represent such tracks. Spacial information is represented by MtData objects.

Access

The Mt2dTrackData object is obtained from the parent MotionTrackerObject.

• MotionTrackerObject::Get2dTrackData(): Returns a new Mt2dTrackData object.
• Mt2dTrackData::Free(): Deletes the given Mt2dTrackData object.

Warning

The returned object is a copy owned by the caller.

  // This example accesses the track data to print the track count.
 
  Mt2dTrackData* trackData = moTrackObject->Get2dTrackData();
  if (trackData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const Int32 trackCount = trackData->GetTrackCount();
  ApplicationOutput("Track Count: " + String::IntToString(trackCount));
 
  Mt2dTrackData::Free(trackData);

Access Tracks

The Mt2dTrackData object provides access to 2D tracks:

• Mt2dTrackData::GetTrackCount(): Returns the number of tracks.
• Mt2dTrackData::GetTrackByIndex(): Returns a copy of the track with the given index.
• Mt2dTrackData::GetTrackByGid(): Returns a copy of the track with the given ID.
• Mt2dTrackData::GetTrackIndices(): Returns a BaseSelect containing the valid indices for user tracks and/or auto tracks.
• Mt2dTrackData::GetTrackByName(): Returns a copy of the track with the given Name.

A copy of a track has to be freed with:

• Mt2dTrack::Free(): Deletes the given Mt2dTrack.

  // This example accesses the track data to loop
  // through all tracks and print their names.
 
  Mt2dTrackData* trackData = moTrackObject->Get2dTrackData();
  if (trackData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // AutoFree takes ownership
  AutoFree<Mt2dTrackData> freeData;
  freeData.Assign(trackData);
 
  const Int32 trackCount = trackData->GetTrackCount();
 
  // loop all tracks
  for (Int32 i = 0; i < trackCount; ++i)
  {
    Mt2dTrack* track = trackData->GetTrackByIndex(i);
    if (track == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // AutoFree takes ownership
    AutoFree<Mt2dTrack> freeTrack;
    freeTrack.Assign(track);
 
    // print track index and name
    const String trackName  = track->GetName();
    const String trackIndex = String::IntToString(i);
    ApplicationOutput("Track " + trackIndex + " : " + trackName);
  }

Access Track Data

A Mt2dTrack object stores several properties:

• Mt2dTrack::GetName(): Returns the name of the track.
• Mt2dTrack::GetId(): Returns the ID of the track. An ID is represented by a MtTrkGid object.
• Mt2dTrack::GetStatus(): Returns the status of the track.

A valid status is:

• ::INVALID_TRACK: Not a valid track.
• ::UNTRACKED: Has not yet been tracked.
• ::TRACKED_VALID: Has been tracked, and is up to date.
• ::TRACKED_STALE: Has been tracked, but needs updating.

A track may only be valid for certain frames. This validity is stored in a BaseSelect object:

• Mt2dTrack::GetFramesWithTrackData(): Returns a copy of a BaseSelect that stores the valid frames for the given track.

    // This example checks for what frames the given track
    // contains 2D tracking data.
 
    BaseSelect* frameRange = track->GetFramesWithTrackData();
    if (frameRange == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // AutoFree takes ownership
    AutoFree<BaseSelect> freeFrames;
    freeFrames.Assign(frameRange);
 
    Int32 seg = 0, a, b;
 
    // loop through all segments of the BaseSelect
    while (frameRange->GetRange(seg++, LIMIT<Int32>::MAX, &a, &b))
    {
      const String segmentBeginStr = String::IntToString(a);
      const String segmentEndStr = String::IntToString(b);
      const String trackName = track->GetName();
 
      ApplicationOutput(trackName + " contains data for the range " + segmentBeginStr + " to " + segmentEndStr);
    }

Position Data

The information on the position of the track for a given frame is stored in a MtData object. Such an object is returned by the Mt2dTrack:

• Mt2dTrack::GetDataForFrame(): Returns a copy of a MtData object for the given frame.
• Mt2dTrack::GetDataForCurrentFrame(): Returns a copy of a MtData object for the current frame of the active BaseDocument.

Spacial information is obtained from that MtData object:

• MtData::GetNormalisedPosition(): Returns the normalized position.
• MtData::GetPixelPosition(): Returns the position in pixel coordinates.
• MtData::GetCameraSpaceDirection(): Returns a ray in camera space corresponding to the position of the track.

  // This example loops through all frames of the footage and
  // checks for each frame if the given track contains data for it.
  // If so, the data is printed to the console.
 
  // get footage range
  const Int32 firstFrame = footage->GetFirstFrameNumber();
  const Int32 lastFrame  = footage->GetLastFrameNumber();
 
  // loop through all frames
  for (Int32 frame = firstFrame; frame < lastFrame; frame++)
  {
    // check if track contains data for the given frame
    if (frameRange->IsSelected(frame))
    {
      // access data
      MtData* frameData = track->GetDataForFrame(frame);
      if (frameData == nullptr)
        return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
      // AutoFree takes ownership
      AutoFree<MtData> freeMtData;
      freeMtData.Assign(frameData);
 
      // get position
      const Vector pos = frameData->GetPixelPosition(footage, true);
 
      // print to console
      const String posStr = String::VectorToString(pos);
      const String frameStr = String::IntToString(frame);
 
      ApplicationOutput("Position for frame " + frameStr + ": " + posStr);
    }
  }

Further Reading

• Motion Tracker Overview
• MotionTrackerObject Manual
• MtFootageData Manual
• Entity Creation and Destruction Manual (Cinema API)