< Previous | Contents | Manuals Home | Boris FX | Next >
The following attributes are available for planar trackers. You will need to call .Run() after changing most. The attributes are available for non-planar trackers as well, though they are likely not to do anything or contain no data. In- plane splines are not currently scriptable.
This list is followed by additional lists that are derived values for 3D planar trackers.
.alphaPolarity Polarity used for an alpha channel in the source imagery as applied to the planar tracker: 1— white is good, 0—alpha is ignored, -1—white is masked out.
.aspectTolerance Allowable frame/frame aspect ratio change for 2D planar trackers. A value of 0.015 means
+1.5% -1.48% (ie 1/1.015)
.autoThreshold AutoMask minimum difference threshold (0..1)
.autoCoverage AutoMask coverage consistency parameter (0..1)
.autoSpread AutoMask spreading distance parameter (0..1)
.BLcorner Bottom-left corner on the current frame, if OUTCOME_OK. This is an XYZ vector in camera-relative coordinates (not subject to Z- Up, Y-Up, etc) where the UV coordinates of the corner are X/Z and Y/Z. Relevant only on keyed frames, never interpolated.
.BRcorner Bottom-right corner on the current frame, if OUTCOME_OK. This is an XYZ vector in camera-relative coordinates (not subject to Z- Up, Y-Up, etc) where the UV coordinates of the corner are X/Z and Y/Z. Relevant only on keyed frames, never interpolated.
.BLkey Bottom-left location in U/V coordinates, if planar tracker is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey. Relevant only on keyed frames, never interpolated.
.BRkey Bottom-right location in U/V coordinates, if planar tracker is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey. Relevant only on keyed frames, never interpolated.
.BLsearch Bottom-left search-box location in U/V coordinates, if planar tracker's search
rectangle is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey.
.BRsearch Bottom-right search-box location in U/V coordinates, if planar tracker's search rectangle is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey.
.CalculatePlanarGridCounts() Calculate the number of horizontal and
vertical grid lines displayed in the tracker, by examining the (already-tracked) tracker on the current frame and applying the grid- spacing preferences.
.centerPos Center 2D position of the planar tracker's reference point on the surface of the plane. X and Y each 0..1
.channel Channel that is tracked: RGB/R/G/B/Luma (0..4)
.detail Detail processing mode (0/1)
.enableAutoMask Enable(1)/disable(0) AutoMask feature. At 2, AutoMask is enabled using RGB processing.
.gridX Number of horizontal grid lines displayed in the tracker interior. Computed when the tracker is created; there is no UI for it except for any scripts.
.gridY Number of vertical grid lines displayed in the tracker interior. Computed when the tracker is created; there is no UI for it except for any scripts.
.isPlanar The tracker is a planar tracker (based on its kind attribute) 0/1 read-only.
.isPlanar3D The tracker is a 3D-type planar tracker. 0/1 read-only.
.layer Layer number that defines the stacking order of the planar trackers. These values are the text-string equivalent of a 64-bit number.
Swap them, don't compute on them!
.lighting Lighting compensation code (0/1/...)
.mainFrame Main key frame upon which the planar tracker was created.
.motionType Motion type, an integer bitmask. Only the values listed on the Planar control panel are permitted. 3D=1. Two-D bits: SCL=2, ROT=4, Aspect=8. 3D: Zoom=16, FOV=32,
Aspect=64.
.PlanarInterpolate(pt) Returns the UV coordinates at the given point
in the 0..1 coordinates of the planar tracker (ie like centerPos). The tracker must be valid on the current frame.
.pln3Dheight Height of the planar tracker, used for 3-D scaling if the tracker is not 3-D solved. If the value is less than zero, it is interpreted not as a height, but as a width, though this is less accurate. If this value is zero, a world-size- based scaling algorithm is used.
.plnRefFrame Planar tracker's reference frame for the current frame. Might be in either direction. -1 if none.
.rotationTolerance Allowable frame/frame rotation search tolerance (deg)
.scaleTolerance Allowable frame/frame scale search tolerance. A value of 0.015 means +1.5% - 1.48% (ie 1/1.015)
.SetPlanarKey(pnt) Moves the tracker on frame to the given UV position (pos), preserving its prior shape. Like dragging the planar tracker rectangle in the camera view.
.SetPlanarSearch(pnt) Moves the tracker's search rectangle on
.SpinPlanarCCW() Spin the corners of a planar tracker counter- clockwise, to fix setup errors by the user (was created CW from top right).
.SpinPlanarCW() Spin the corners of a planar tracker counter- clockwise, to fix setup errors by the user (was created CW from bottom left).
.SpinPlanarRev() Reverse and spin the corners of a planar tracker, to fix setup errors by the user (was created CCW from top right)
.TLcorner Top-left corner on the current frame, if OUTCOME_OK. This is an XYZ vector in camera-relative coordinates (not subject to Z- Up, Y-Up, etc) where the UV coordinates of the corner are X/Z and Y/Z
.TRcorner Top-right corner on the current frame, if OUTCOME_OK. This is an XYZ vector in camera-relative coordinates (not subject to Z- Up, Y-Up, etc) where the UV coordinates of the corner are X/Z and Y/Z.
.TLkey Top-left location in U/V coordinates, if planar tracker is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey. Relevant only on keyed frames, never interpolated.
.TRkey Top-right location in U/V coordinates, if planar tracker is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey. Relevant only on keyed frames, never interpolated.
.TLsearch Top-left search-box location in U/V coordinates, if planar tracker's search rectangle is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey. Relevant only on keyed frames, never interpolated.
.TRsearch Top-right search-box location in U/V coordinates, if planar tracker's search rectangle is keyed on this frame (if so, all 4 corners MUST be keyed). This is an animated GenKey. Relevant only on keyed frames, never interpolated.
The following attributes are available only for tracked (OUTCOME_OK) 3D planar trackers and with .pln3dvalid nonzero. They are derived indirectly from the planar tracker's TL/TR/BL/BRcorner locations and as such are read-only. The scaling of the coordinate system is arbitrary: the transform's translation, plane width, and plane height can all be multiplied by an arbitrary factor (see the next subsection!).
.pln3dvalid The corner locations can be successfully converted to 3D information including FOV and rectangle aspect.
.plnaspect The aspect ratio (width/height) of the rectangle.
.plncenter The UV coordinates of the (0.5,0.5) center of the tracker, ie independent of .centerPos
.plnfov The imputed lens FOV of the camera.
.plnheight The height of the plane.
.plnpitch The pitch angle (deg) of the plane relative the camera.
.plnroll The roll angle (deg) of the plane relative the camera.
.plnscale The imputed lens scaling factor of the camera.
.plntrans The assembled camera-relative 3D transform of the 3D plane. It is X-right, Y-down, Z- forward.
.plnwidth The width of the plane.
.plnyaw The yaw angle (deg) of the plan relative the camera.
The following special attributes are intended for 3D planar trackers that have not only been tracked, but 3D solved as well, in addition to the rest of the scene (ie, a moving object if the planar tracker is parented to it).
The key point is that solved planar trackers allow a specific 3D scaling value to be computed such that the plane falls exactly on its computed 3D location. The planar tracker's transformation matrix, width, and height are scaled to match the overall 3D environment. Depending on the planar motion mode, this may occur on a frame-by-frame basis and is thus inherently jittery, unlike a plane placed into the 3D environment.
If the tracker has not been solved as part of the overall scene, a default position of 0,0,0 is used so that the plane passes through the origin (users should ensure the camera is looking in that general direction!).
These attributes are read-only.
.crplntrans Camera-relative transform for the current frame: from the plane to the camera's coordinate system. Supplied in the selected axisMode along with ancillaries such as crplnrowA, crplnx, crplnry, etc.
.prplntrans Parent-relative transform for the current frame: from the plane to its parent moving object, if it has one, or to the world coordinate system, if not. Supplied in the selected axisMode along with ancillaries such as prplnrowA, prplnx, prplnry, etc.
.wplnheight Plane's height in the world coordinate system. Determined on the tracker's planar reference frame; the transform is scaled to hold this constant.
.wplntrans World transform for the current frame: from the plane to the overall world coordinate system. Supplied in the selected axisMode along with ancillaries such as wplnrowA, wplnx, wplnry, etc.
.wplnwidth Plane's width in the world coordinate system. Determined on the tracker's planar reference frame; the transform is scaled to hold the
height constant, so the width varies only if the aspect does.
©2023 Boris FX, Inc. — UNOFFICIAL — Converted from original PDF.