Shot

< Previous | Contents | Manuals Home | Boris FX | Next >

If you need to determine whether the shot’s source is a single-file ‘movie’ of some kind, or an image sequence, test whether or not imageName is null at the start of the shot. This is a sure test even as new movie and image file extensions come into existence in the future.

Note that many additional settings are available via the image preprocessor settings accessed from shot.live and shot.preset and the stereo geometry settings, shot.stereo.

IMPORTANT : .backPlateWidth and .effBackPlateWidth were different in SynthEyes 2210 and earlier. They now include the effect of .squeeze, so that focal lengths will correspond to lens barrel values independent of squeeze. For squeeze-sensitive uses, you may need to adjust the horizontal and vertical sizes that you export.

.actualLength actual length of the shot, as currently available, in frames (fields if interlaced). Will be 10 if the shot is not readable.

.AdjustTrackers(md) Adjusts all the tracker positions to reflect the

current state of the image preprocessor. Mode md is a combination of these bits: 1: remove stabilization (applies distortion to trackers!), otherwise apply stabilization (removes distortion from trackers!); 2: include effect of stabilization; 4: include effect of distortion; 8: include effect of pad/crop.

.alphaImageName File name of an attached alpha channel image, for the current frame. Read-only. Due to preferences, this may be non-null, ie there be an attached alpha channel, even if

.alphaName is null.

.alphaName Base (typically first) file name for an attached alpha channel sequence. May be null—if so, the preferences are used to determine if there is an attached alpha channel. Read/write.

Flushes the shot cache when written.

.alphaLevels Number of levels of alpha present if alpha is being used on the roto panel to control what area is tracked.

.aspect shot’s (net) image aspect ratio (1.333, 1.777, 2.35 etc) as output from image prep .

Writable, but changes aspectRef: only do this

early, during shot setup, then Flush() the cache.

.aspectRef shot’s reference aspect ratio, normally the input of image prep, or the output in Apply mode, ie that of the underlying imagery. (Read only, writing .aspect changes

.aspectRef.)

.aspectSrc shot’s source aspect ratio, into image prep (Read only)

.backPlateWidth Effective post-padding and squeeze sensor (back plate) width setting (mm, computed, read only). Preferable to use

.effBackPlateWidth for clarity. Divide by aspect to obtain height; divide this width by squeeze for the actual sensor width. See also

.rawBackPlateWidth.

.batchMode What should be done if the file is batch- processed: -1: nothing; 0: track & solve; 1: render; 2: track only; 3: solve only. Same as

.renderReady for historical reasons, use this one!

.bgChroma Blue/green-screen chrominance control

.bgCoverage Blue/green-screen coverage control

.bgHue Blue/green-screen hue control

.bgHueTolerance Blue/green-screen hue tolerance

.bgEnable Blue/green-screen subsystem enable

.bgLuma Blue/green-screen luminance control

.bgRadius Blue/green-screen radius control

.biastime offset time of this shot’s first frame vs global, seconds

.bigBlipSize See Feature panel’s Advanced dialog

.bigBlipDensity See Feature panel’s Advanced dialog

.blip Array of blip objects for each frame . See the Blips section below.

.cam Camera object for this shot (Read only)

.decimate Shot decimation ratio for solving, ie with decimate = 3, only every third frame will be solved. Normally one!

.doCorners Locate corners during auto-tracking

.edgeContrast Off-axis required edge contrast

.edgeCurvature Allowable change in direction in a single edge

.edgeCutoff Numbers of pixels to ignore at the end of an edge

.edgeIntersect Maximum distance from an edge to a corner

.edgeIntersectMargin A few extra pixels for a safety zone

.edgeMinLength Minimum edge length

.edgeSaturated Edge intensity corresponding to a fully- saturated color, used for display only.

.edgeSharpness Minimum required angle between two edges for a corner

.edgeSize Corner/Edge detection filter width

.edgeThreshold Minimum required edginess

.edgeUsable Usable pixels at the end of an edge, once cut off.

.effBackPlateWidth Effective post-padding plate width and anamorphic squeeze (read-only, mm). Divide by aspect to obtain height; divide this width by squeeze for the actual sensor width. See also

.rawBackPlateWidth

.enableRolling Enable rolling-shutter compensation in the solve

.exposure Exposure time in 1/seconds, if available, ie atof(shot.MetaValue("exposure")). For example, the value is 200 for a shutter time of 1/200th. Read only.

.exposureAdjust Shot parameters panel, adjusts EXR floating point image scaling.

.Flush() Clear the shot cache

.FlushDiskCache() Clears the disk cache (only) for this shot

.frameCount Number of complete frames in the shot, independent of interlacing mode. Be sure to set this, based on actualLength, after opening a new shot.

.frameFirstOffset The frame number embedded in the first frame of an image sequence, potentially used if the .matchFrameNumbers preference is active. Read-only.

.frameMatchOffset Equals frameFirstOffset if

.matchFrameNumbers is active, or zero otherwise. Typically useful for planning image vs movie exports. Use .frameUIOffset to offset to/from user values. Read-only.

.frameUIOffset Equals frameFirstOffset if if

.matchFrameNumbers is active, or the “First Frame is 1” preference if not. This is the actual value that frame numbers for this shot are being offset by in the user interface.

Read-only.

.geoAlphaPolarity Interpretation, if any, of how the alpha channel affects GeoH tracking: doesn't, positive, negative.

.geoChannel Channel selection (RGB, luma, red, etc) used for all geometry tracking. See Tracker.channel

.handHeld tracker prediction mode: 0: predict, 1: sticky, 2: multi-tracker predict, 3: current position (special use)

.height image height, pixels (Read only)

.hiRezFactor Interpolation factor used for supervised trackers, from the shot parameters panel.

.Image() Returns the Sizzle Image object for the current frame after preprocessing, ie the output of the RAM cache.

.imageName image file name for current frame (sequence), or empty string if not an image sequence (Read only)

.ImagePosition(xyzvector) The position of the xyz vector (in world

coordinates) in UV coordinates on this shot. Returns null if the coordinates are behind the camera or otherwise unreachable.

.insideSpline(name, uvpos) Returns 1 if the uvposition point is inside the

named spline at the current frame, or 0 if not.

.interlace interlace mode (a small integer)

.is16Bit Image format reported from the image reader by reading the current frame: 0: 8-bit, 1: 16- bit, 2: half-float(16-bit), 3: float (32-bit) (read- only)

.isSurvey If set, shot is a survey shot with an IFL that jumps around.

.keepAlpha Store alpha channel even if SynthEyes is not using it, typically for output from the image preprocessor.

.left If the current shot is part of a stereo pair, returns the left shot (which may be this same shot), or null

.length shot length, frames (Read only)

.lensflowState Text string used by scripts, primarily lens workflow, to keep track of what is happening, to facilitate and check lens workflow undo.

Other scripts may use it to help export lens distortion. The first character is 1 or 2 to indicate the respective workflow, possibly

followed by other encoded characters. Null string if lens workflow hasn’t been run.

.liTracking Whether or not light-invariant tracking is enabled for this shot.

.live The “live” image preprocessor preset, use to access the current parameters.

.LoadPrepSetsFromFile(kind, fnm) Load or update this shot’s prepsets from

those stored in a .prp file earlier by SavePrepSetsToFile(). The prepsets are labeled as the specified kind: scene:0, imported:1, preference:2. Returns the number of affected prepsets, or -1 in the case of an error (such as unreadable file). See also Scene.UpdatePrepSetsFromFile().

.matchFrameNumbers Whether or not the frame number display is

offset to match the frame numbers of the image sequence. This used to be a preference-only setting, but is now stored per- shot in the scene.

.MetaCount() The number of metadata values on the current frame

.MetaNameByIndex(n) The nth metadata item's name (string), on the

current frame.

.MetaPresent(metanm) Zero or one depending on whether or not

metadata with the given name is present on the current frame.

.MetaValue (metanm) The metadata with the given name, on the

current frame. The value is always a string; convert to an appropriate value as needed. See "Shot Metadata" in the SynthEyes User Manual for information about pre-defined metadata names.

.MetaValueByIndex(n) The nth metadata item's value, on the current

frame. The value is always a string; convert to an appropriate value as needed.

.NewGeoH() Creates a new GeoHTrack object on this shot, initialized at the current frame.

.nm shot’s image file name (for a sequence, an ifl). If you write this, call Flush() afterwards, and set the frameCount correctly based on actualLength.

.nnBlipDensity Neural net desired number of blips per thousand pixels.

.nnMinContrast Neural net minimum contrast for auto-tracking blips.

.nnMinAmplitude Neural net minimum total blip amplitude for auto-tracking.

.nnModel Neural net model name for auto-tracking: the folder name for the model.

.nnTileHeight Neural net tile height for auto-tracking.

.nnTilesPerBatch Neural net tiles per batch setting for auto- tracking.

.nnTileWidth Neural net tile width for auto-tracking.

.obj List of objects using this shot (Read only, new

(moving) object supported)

.parity starting frame parity, if interlaced (Read only)

.pixasp shot’s pixel aspect ratio (0.88, 1.0, etc), determined from image aspect and resolution. (Read only)

.preset List of image prep presets for this shot. Use “.live” to access the one that is live, do not access it within the .preset list. Access with numbers or preset names.

.previewCompression Text string of file-format-specific compression

settings. Manually set up compression, then examine this string using the synthia command: camera 1's preview compression.

.previewFile File where the preview movie will be saved

.previewSettings Text string of system settings for preview movies — which channels. Do some previews to see current values.

.processFormat Image preprocessor pipeline processing format: 0: 8-bit, 1: 16-bit, 2: half, 3: float (32- bit). Special values: -1: use image-reader’s recommendation, 100: force a Half buffer to be used—only if no image preprocessing will be performed at all (very slow).

.queueLength Queue length for this shot, frames.

.rate frame rate, frames per second, does not have to be integer

.rawBackPlateWidth Underlying sensor (back plate) width for the

imagery, before the effect of padding or anamorphic lenses. Read/write.

.rawHeight Height of the image as reported by the image reader, before any preprocessing.

.rawLength Length of the shot as reported by the image reader, always in frames regardless of interlace mode.

.rawWidth Width of the image as reported by the image reader, before any preprocessing.

.readerType A read-only string describing the reader being used for the shot, eg ‘0’ for a null reader (no shot), ‘i’ for an image sequence, ‘e’ for an empty reader (render camera), ‘P’ for the SynthEyes-native ProRes reader.

.Rectify(udfnm, rdfnm, args, Cancellable) Implementation routine for the

Rectify Lens Grid operation. The udfnm and rdfnm parameters are the UVMap file names to be written for undistortion and redistortion. All the other options are compressed into the args string. The fourth argument can be a Cancellable object (for running in the background), or null. See rectify.szl for example code and details.

.RedistortImageMap(clp, walp) Returns an Image that is the redistortion UV

map image for the current configuration of the shot. Always a float image that is clipped if clp is nonzero and with alpha if walp is nonzero. May depend on the current frame number.

.redistortSequence File name for the first file in an exported UVmap redistortion sequence.

.RegenAspect() Regenerate some aspect ratio information after padding and stabilization information has been changed. Generally done automatically, but not when manipulating image preprocessor settings.

.renderCompression Text string of file-format-specific compression

settings. Manually set up compression, then examine this string using the synthia command: camera 1's render compression.

.renderFile File where the sequence will be saved

.renderReady 0/1. Sequence should be rendered by the batch processor if this file is submitted for processing. Alias of .batchMode, use

.batchMode for ongoing work.

.renderSettings Text string of system settings for render — which channels. Do some save-sequences to see current values.

.ResetPreset() Reset all the non-stabilizer (live) image preprocessor settings.

.ResetStabilizer() Clears the stabilizer settings to their defaults.

.Render() Renders the shot sequence to disk (ie Save Sequence) using the current render settings. Returns 1/0 if the render succeeds/is canceled.

.right If the current shot is part of a stereo pair, returns the right shot (which may be this same shot), or null

.rollingShutter Rolling-shutter compensation fraction: the proportion of the frame time required to read out the image.

.savedHeight Raw (pre-preprocessor) image height, as saved at the end of various operations such as Edit Shot. May be different than the actual image height, if the images have been replaced by a proxy, or various image preprocessor options are active. Useful when the original images are no longer available.

.savedWidth Raw (pre-preprocessor) image width, as saved at the end of various operations such as Edit Shot. May be different than the actual image width, if the images have been replaced by a proxy, or various image preprocessor options are active. Useful when the original images are no longer available.

.SavePrepSetsToFile(kind, fnm) Save prepsets of the designated kind to a

.prp file, for later reloading by Shot.LoadPrepSetsFromFile() or Scene.UpdatePrepSetsFromFile(). Kind values: all:-2, selected:-1, scene:0, imported:1, preferences: 2. Returns the number of presets written (ie of the specified kind), or -1 if the file can’t be written.

.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.

.shutterAngle Shutter angle used for perspective-view renders of this shot (in degrees).

.shutterPhase Shutter phase used for perspective-view renders of this shot (in degrees).

.skipFrame frame is skipped for autotracking and solving

.smallBlipSize See Feature panel’s Advanced dialog

.smallBlipDensity See Feature panel’s Advanced dialog

.spline List of splines for the shot

.squeeze Anamorphic squeeze factor

.start start frame number

.stereo Returns a Stereo Geometry object defining the camera/camera geometry of stereo shots, or 0 for non-stereo cameras.

.stereoType stereo type: 0:none, 1:left, 2:right

.stop ending frame number

.storeFormat Image preprocessor pipeline result format for storage, tracking, and output: 0: 8-bit, 1: 16- bit, 2: half, 3: float (32-bit). Or -1 if it is following .processFormat.

.syncCode Motion capture synchronization control

.TimeShift(df) Shifts the ENTIRE shot and camera and attached objects and trackers and meshes and ... by df frames. If df is positive, keys move to larger frame numbers, ie frames are being added at the beginning of the shot. If df is negative, keys move to smaller frame numbers, ie frames are being removed.

Complex and risky operation!

.trackerFilterType Type of filtering used for the high-resolution view of supervised trackers.

.UndistortImageMap(clp, walp) An Image that is the undistortion UV map

image for the current configuration of the shot. Always a float image that is clipped if clp is nonzero and with alpha if walp is nonzero. May depend on the current frame number.

.undistortSequence File name for the first file in an exported UVmap undistortion sequence.

.uniqueID A unique ID string (representing a 64-bit integer)

.uvMapFileName User-set filename for writing the undistortion UVMap image, from Shot/Write distortion UVMaps. The redistort map has the preference string appended, eg "Inverse".

.Validate() Flushes any frames in the cache that do not match the current settings. Call before requesting image width/height after changing shot or preprocessor parameters.

.width image width, pixels (Read only)

.WriteColorMap(fnm,sides) Writes a 3-D .cube colormap with the

dimensionality given. Returns 1 on success, 0 on failure.

.WriteRedistortImage(filenm, clip) Writes a UVMap image to redistort an

undistorted (CGI) image back to a distorted image (for compositing) to the given filename.

If clip is 1 or missing, UVMap data is clipped to 0..1 range, if not, values <0 or >1 are permitted in order to access overscan areas. Returns 1 on success, 0 on failure. Can depend on current frame#! See also RedistortImageMap and Scene.InvertUVMap.

.WriteRedistortSequence(fnm, cmp, flt, walp, clip) Writes a sequence of

UVMaps, starting at the given first filename (must include any leading zeros). Cmp is the compression specification string; flt=1 for a full floating-point map or =0 for 16bit; walp is 2 to write premultiplied alpha, 1 for non- premultiplied, or 0 for no alpha; clp=1 to clip to 0..1, or =0 to allow out-of-range color values (safety areas).

.WriteUndistortImage(filenm, clip) Writes a UVMap image to undistort the

source as-shot images into linear images to the given filename. If clip is 1 or missing, UVMap data is clipped to 0..1 range, if not, values <0 or >1 are permitted in order to access overscan areas. Returns 1 on success, 0 on failure. Can depend on current frame#! See also UndistortImageMap.

.WriteUndistortSequence(fnm, cmp, flt, walp, clip) Writes a sequence of

< Previous | Contents | Manuals Home | Boris FX | Next >