< Previous | Contents | Manuals Home | Boris FX | Next >
Tracker
The following attributes apply to all trackers, with possible fine print for planar trackers. See the following sections for attributes applicable specifically to planar trackers.
.altColor An alternate color for the trackers, see .color,
.primcolor, .netcolor and Scene.useAltColor and the tracker's Use Alternate Color menu item.
.asp tracker aspect ratio, horizontal/vertical. 1.0 is square. Animated but not genkey, see .sizeuv
.autokey automatically add a key after this many frames
.AvgImgColor() Returns a vector of the average color of the image region in the interior of the tracker at its 2D location on the current frame. Computed with full floating-point range if the image supplies it. Returns null if the tracker is not valid or offscreen on this frame.
.AvgImgColor3D() Returns a vector of the average color of the image region in the interior of the tracker at its solved 3D location on the current frame, or seed location if it is not solved but has seed lock coordinates. Uses the 2D location if the tracker is not solved. Computed with full
floating-point range if the image supplies it. Returns null if the tracker is not solved and not valid on this frame, or if the tracker is behind the camera or offscreen.
.axisLock Combination of bits for axis locks on the tracker: X/Y/Z = 1/2/4, independent of axis mode. If 8 is present, locks are to zero coordinates, otherwise to .lockPos
axisAdjLock Combination of bits for axis locks on the tracker: X/Y/Z = 1/2/4, adjusted for axis mode. If 8 is present, locks are to zero coordinates, otherwise to .lockCoord
.BakeOutOffset() Remove any offset track, first setting keys on any frame with an active offset, so the track itself doesn't change. The offset enable and value keys are cleared.
.blipFrame For auto-trackers, the frame number of the start of the blip chain for this tracker, ie the frame corresponding to blipNumber, or -1 for supervised trackers. Check this number for consistency!
.blipNumber For auto-trackers, 0-based Blip number of this tracker on .blipFrame. or -1 for supervised trackers. Check this number for consistency!
.brightness Brightness of mini-tracker-view
.cliffhanger Cliff-hanger mode, ie supervised tracking near edge.
.ClearIllumination() Clear illumination data from the tracker.
.Clone() Clone the tracker, returning the new one, which will have a new name based on appending Clone and a number to the existing name (replace as needed).
.color Color in display, 24b little-endian RGB value.
Is 0x818283 (8487555) if the color is the default determined by the preferences. See also .primColor, .altColor, .netcolor, Scene.useAltColor
.CombineFrom(from_tk) Combines tracker from_tk into this tracker,
similar to Edit/Combine Selected but this is the routine used for Coalesce operations. You probably want to delete from_tk, though you don’t have to.
.coordinates The tracker’s image (pixel) coordinates in the current frame. Integer values correspond to
the center of the pixel, add 0.5 to each value to get values correspoinding to the edges.
.crossHair0 offset to the end of the first user crosshair bar (~horizontal)
.crossHair1 offset to the end of the second user crosshair bar (~vertical)
.direction Same as isBackward, but writing it causes the keys and enable track to be adjusted to maintain existing tracking data.
.dist Distance constraint value.
.error tracker’s reported root-mean-square tracking error, in units of U, not hpix.
.errorHpix trackers's reported root-means-square tracking error in hpix (ie the user-visible value).
.fom 0 to 1 figure of merit for tracking quality on this frame.
.frameError Trackers 2D vs 3D error on this frame, in hpix. NOTE: if the tracker is not valid or is not solved, the error is zero, so the trackers with the smallest frame error will be unsolved or invalid. Be sure to check that first.
.gain Gain of mini-tracker-view
.gotFar Tracker was solved as far (ie even if a non-far solution was desired). Use for all exports and solved positions
.handAnimated Hand-animated on this frame
.HandInterpolate(mode) Spline-interpolates relevant frames near the
current frame, according to the mode. Mode=0 is normal, and is all nearby frames, 1 is only the current frame, -1 is all hand- animated ranges on this tracker. Call this after changing handAnimated, isEnabled, or setting tracker position keys on the tracker.
.illumination RGB vector of the possibly-animated illuminating color of the tracker, if it has been set up (animatable).
.illumB Possibly-animated 0..1 blue component of the tracker, GenKey.
.illumCam Camera that the tracker is attached to (read only)
.illumColor The illumination value as a 24-bit integer color (instead of a vector).
.illumG Possibly-animated 0..1 green component of the tracker, GenKey
.illumR Possibly-animated 0..1 red component of the mesh, GenKey.
.illumShot Shot that the tracker is attached to. (read only)
.isIlluminated Tracker has an illumination track (illumR/G/B).
.isBackward tracker tracks backwards. Writing it affects only the flag, not the keys or enable track. Use during setup
.isDone tracker has been marked “done” (locked). When locked, many script attributes will not be changeable, just like on the tracker control panel: you must temporarily clear isDone before changing the tracker.
.isDoneFancily Reads the same as isDone. When written to zero, checks for auto-to-supervised transitions and makes some adjustments to search size. When written to 1, makes sure that all frames where isEnabled is false report that the tracking data is invalid, preventing possible inconsistency in stored data when the enable is changed without a subsequent re-track pass. (Used by Synthia.)
.isEnabled tracker is enabled on the current frame
.isExported tracker should be exported
.isFar Far tracker status. When read, gotFar if solved, otherwise wantFar. When written, sets both wantFar and gotFar.
.inFront Predicted 3-D position in front of, not in back of, the current camera.
.isGolden tracker is golden. Can only be written to 1, can not be cleared.
.isHandAnimated Whether it might have some (splined) hand animation: more specifically, the number of keys on the handAnimated track.
.isKeyed Has a key on this frame. Set to add a key at the current position, clear to 0 to remove a key
.isSeed tracker is a seed point
.isSel tracker is selected. When writing, the tracker selection set is cleared only if the value is exactly 1. Use a value of 2 to add to the existing selection.
.isSelected tracker is selected. Does not clear the selection set.
.isShown tracker is shown in the viewports
.isSolved tracker’s position has been solved (0=no, 1=normal, 2=“individual motion-capture”)
.isZWT Is “Zero-weighted” tracker, ie is solved immediately without affecting the scene. See
.isZWTrun
.isZWTrun Changes the ZWT status, but additionally when .isZWTrun is set to 1 (ie be a ZWT),
.RunZWT is immediately called. Note that when many trackers become ZWT simultaneously, .isZWT and UpdateZWT are preferable since they update all trackers in parallel.
.key Key location u/v. Write to add a key at the given location.
.kind 0/1/2/3/4/5: match, black spot, white spot, symmetric, planar, neural.
.lockCoord Vector, coordinates the target is lock to, or its seed position, in current coordinate axis mode.
.lockPos Vector, coordinates the target is locked to, or its seed position. Always in Z-Up coordinates!
.MCalc() Recalculates the motion-capture spline for the tracker
.MClear() Clears any motion-capture path for the tracker
.mlength Length of the tracker’s individual (motion- capture) path, if any.
.mvalid Whether the tracker’s individual path, if any, is valid on this frame. 2:key, 1:valid, 0:invalid.
Can be read, or only be written to zero.
.mvec Tracker’s motion-capture path position (vector) on the current frame. Creates a key.
.netcolor Net color: the default value is resolved to the net color using the applicable preferences
.nm tracker’s name
.nnMinAmplitude Minimum amplitude threshold for detection in neural-net supervised tracking, if non-zero. If zero, a network-specific default value will be used.
.nnMinContrast Minimum contrast setting for neural-net supervised tracking, if non-zero. If zero, a network-specific default value will be used.
.nnModel The folder name within NNModels of the selected neural net model for supervised tracking of this tracker. Only relevant when the tracker’s type is set to neural net.
.nnSearchFraction A fraction of the tracker size that will be searched for a suitable feature during the refinement stage of supervised neural tracking, if non-zero. If zero, a network- specific default value will be used.
.nnSpotReduction The neural network examines only this fraction of the interior of the supervised tracker, leaving some border around the outside to benefit the first rough search in supervised neural tracking, if non-zero. If zero, a network-specific default value will be used.
.obj the object for this tracker. Do not change this within a loop such as obj.trk, etc – it is effective immediately.
.offset Offset channel from 2-D tracking location to desired tracked point (genkey, see attributes intro).
.offsetActive Tracker offset channels are being used, animated.
.offsetActiveIsKeyed Key in offsetActive at this frame. Similar to a
genkey, write to 1 to set a key, 0 to clear a key, or -1 to truncate keys.
.offsetPresent Checks to see if the offset channel has animation, or if the first key is NOT at 0,0. Read only.
.opposite The matching opposite tracker of a stereo pair, if this is a member of a stereo pair. Read only.
.outcome A numeric code reflecting the tracking results on this frame, see below.
.ox,.oy,.oz,.ovec tracker’s position relative it’s host camera or object, a constant. See vector attributes below. Only ovec is writable.
.pegged If set, tracker will be pegged exactly at the specified coordinates, subject to axisLock.
.pointingDirection The pointing direction from the camera towards the feature being tracked, on the current frame, in camera coordinates. Takes into account lens distortion and 360VR status. Neither the camera nor tracker must be solved, but the lens field of view must be set. Returns null if the tracker is not solved on the current frame.
.polarity Combination of bits for desired prealignment axis polarity: X/Y/Z positive = 1/2/4, X/Y/Z negative = 0x10/0x20/0x40.
.primColor Primary color slot, see .color, .netcolor,
.altColor
.pu Predicted 2-D horizontal position, ie that of the solved 3-D position. Equivalent to .puv.u.
-1 to +1 (Read only)
.pv Predicted 2-D vertical position, ie that of the solved 3-D position. Equivalent to .puv.v. -1 to
+1. (Read only)
.puv Predicted 2-D position as seen from the active camera, ie that of the 3-D solved position, as a point (Read only)
.Run() Re-run the tracker at the current frame. Call after using attributes below to make sure that the tracker is in a consistent state.
.RunZWT() Rerun the ZWT calculation to immediately determine this tracker's location (if it is a ZWT). See also .isZWTrun and Obj.UpdateZWT()
.scriptDefined (This entry is only a place-holder, there is no attribute with this name.) You can add new attributes to this type, see Script-Defined Attributes.
.seedu Predicted 2-D horizontal position of the tracker's 3-D seed position (lock coordinates), assuming it is a seed. Equivalent to
.seeduv.u.
.seedv Predicted 2-D vertical position of the tracker's 3-D seed position (lock coordinates), assuming it is a seed. Equivalent to
.seeduv.v.
.seeduv Predicted 2-D position (point) of the tracker's 3-D seed position (lock coordinates), assuming it is a seed.
.shot the shot for this tracker
.size tracker horizontal size, 0 to 1. Animated but not a genkey. See .sizeuv for the genkey.
.sizeuv Point consisting of the u and v sizes of the tracker, as a genkey (with .sizeuvIsKeyed,
.sizeuvKeyType, etc)
.smooth smoothing region between earlier/later keys
.srch Search-region size, as a point (genkey)
.srchu horizontal search-region size, 0 to 1 (animated, not genkey)
.srchv vertical search-region size, 0 to 1 (animated, not genkey)
.target Target tracker that this tracker is locked to.
.u tracker’s horizontal position on this frame, -1 to +1, ie .uv.u.
.uniqueID a unique string (specifying a 64-bit integer) for each tracker in the scene
.uv tracker’s position as a point
.v tracker’s vertical position on this frame, -1 to
+1, ie .uv.v.
.valid a valid image position is available for this frame
.valid3d a valid 3-d position is available for this frame
.wantFar Tracker should be solved as far (applies to seed coordinates)
.weight Weight given the tracker during solving. Use “.isZWT” to make it a “zero-weighted” tracker. Weights of zero or less will cause the frame to be ignored during solving, but each regular tracker should have many non-zero weighted frames.
.willDelete 1 if the object will be deleted after the script completes. Can be changed to control what will happen.
.wx,.wy,.wz,.wvec Tracker’s current 3-D position, taking into account host camera/object motion. Read only.
The tracker’s outcome code reflects what happened when a given frame was tracked. It is a logical OR of several bits, as follows:
OUTCOME_RUN = 1
OUTCOME_ENABLE = 2 -- mirrors the enable track
OUTCOME_OK = 4 -- usable u/v present on this frame
OUTCOME_KEY = 8 -- there is a key here (OK will be on too) OUTCOME_JUMPED = 16
OUTCOME_OUTASIGHT = 32
You can examine the outcome code on a particular frame as part of a 2-D export script, or write to the outcome code as part of an importer. The outcome code reflects other portions of the SynthEyes scene file, notably the tracker keying and enable tracks, and it is must be kept synchronized with them to avoid an “inconsistent” scene that can produce errors.
©2023 Boris FX, Inc. — UNOFFICIAL — Converted from original PDF.