Hi guys!
I’ve just posted an introduction to our new Instant Tracking feature - read that post first to understand why this one exists!
This post is to share all the internal details of our current InstantTracker API and to share an example project for you to play with. We’d also love to hear your thoughts on the current API and any other ideas you have for it.
Instant Tracking is exposed through a simple API, via the Z.InstantTracker object, which like all Zappar objects, you can construct by calling Z.InstantTracker() in a script.
This is the API exposed by that InstantTracker object:
class InstantTracker {
// Get / set whether tracking is enabled
// True by default - to save resources be sure to call enabled(false)
// when no longer required (for example if your InstantTracker is in
// a sub-symbol as part of a larger experience)
enabled() : boolean;
enabled(v: boolean): this;
// The anchor managed by this Instant Tracker
// Set the relativeTo property of a content group to this object
anchor() : Node;
// Set or reset the anchor transform relative to the camera
// Pass in the camera-relative position for the anchor, and one
// of the orientation options (described later)
setAnchorTransformFromCamera(
position: number[],
transformOrientation: InstantTracker.TransformOrientation
): this;
}
The transformOrientation parameter to setAnchorTransformFromCamera allows you to ensure that content placed relative to the anchor initially faces in a known direction. Here are the current options for that parameter:
enum InstantTracker.TransformOrientation {
// “Ground-like” options
"ground",
"z_up_y_away_from_user",
"z_up_y_heading",
// “World-like” options
"world",
"y_up_minusz_away_from_user",
"y_up_minusz_heading",
// Don’t change the world-relative orientation when setting
// the position part of the transform
"unchanged"
}
The ground-like options all have the z axis pointing upwards in the world (away from gravity), and the world-like ones have their y axis pointing upwards. The option names describe how the orientation around that “up axis” is determined.
The demo content uses z_up_y_heading during the initial placement gesture, and then unchanged for subsequent updates, but feel free to edit the script in the example to get a feel for the other options.
If you hold your finger down that will effectively call setAnchorTransformFromCamera every frame, so by holding down for the initial placement and moving both your finger and the device around you’ll be able to see these options in action.
Here’s the example scene for you to play with:
Instant Tracking Forum Demo.zpp (3.9 MB)
The original model is from The Cleveland Museum of Art on Sketchfab. It’s open access so we can freely share it in example content without needing attribution, but we’re happy to give them a shout out anyway!
All of the important stuff happens in the script node, which is quite heavily commented.
A few points to note:
- The CustomAnchor in the hierarchy means Studio’s tools for view manipulation can be used when editing the content. It isn’t needed by the
InstantTrackerat all (the script immediately resets the relativeTo of the tracked group to the InstantTracker anchor). - The InstantTracker API is not yet finalized so it has not been added to Studio’s TypeScript definitions yet. Therefore if you just write
Z.InstantTracker()Studio will highlight a syntax error. You need to tell Studio you know more than it does using(Z as any)to opt-out of the type checking for accessing members. - The TypeScript definitions are also used to determine the minimum version required when publishing an experience, so until these are in place the experience will still load on older versions of Zappar without InstantTracker support. Therefore we’ve added some manual checks that the relevant API is present, and a scene-side message if InstantTracker is not supported. When the API is promoted to stable then this won’t be needed.
I’ll follow up with some more thoughts and open questions on the API, but that should be enough to get you started.
Have fun!
It looks very promising.