Animation

Deserialisation constructor.

Create a new animation with default settings.

Frames are always written as PNG. Lossy formats would compress the images before a video encoder ever sees them, which is the wrong order to do it in; lossless alternatives are all considerably larger; and PNG is the only one of them which carries the transparency the capture settings can ask for.

Largest number of frames we are willing to write. Half a million frames is nearly six hours of footage at 24 fps, which ought to be plenty for everyone.

Fastest playback rate, in frames per second.

Largest capture size, in pixels, along either axis.

The largest allowed canvas zoom.

Smallest sensible number of frames.

Slowest playback rate, in frames per second.

Smallest capture size, in pixels, along either axis.

The smallest allowed canvas zoom.

Gets or sets the folder new animations put their output underneath. Remembered between sessions, so a user who keeps their renders somewhere specific only has to say so once.

Gets the number of bindings in this animation.

Gets all bindings in this animation.

Gets or sets whether canvas captures include the canvas background colour.

Gets or sets whether the resolution is the quantity the user sets, leaving the region to follow from it and the zoom. When false the region and the zoom are both free and the resolution is derived.

Gets or sets the canvas capture height in pixels. See CanvasWidth for how the size relates to the region and the zoom.

Gets or sets whether canvas captures include warning and error balloons.

Gets or sets the region of the canvas which is captured, in whole canvas units.

Whole units on purpose. Object pivots are integers, so an integer region at an integer zoom puts every capsule edge on a whole pixel; a region picked at a fractional offset would shift the entire capture by that fraction and blur every edge at 100%.

An empty region means none has been picked yet. EnsureCanvasRegion(Document) replaces it with one framing the whole document, which the animation window does the moment it shows an animation and the server does before a run.

With a fixed resolution only the centre of an assigned region is kept, the size follows from the resolution and the zoom. Otherwise the region is taken as is and the resolution is recomputed.

Gets or sets the file name template for canvas captures. See FormatFileName(string, int).

Gets or sets the canvas capture width in pixels.

The three canvas quantities, region, zoom and pixel size, are tied together by size = region × zoom. Which of them gives way is decided by CanvasFixedResolution: with a fixed resolution the region is resized about its centre to keep the equation true, otherwise the size is recomputed. A size assigned while the resolution is free stands only until the next region or zoom change overwrites it.

Gets or sets whether canvas captures include wires.

Gets or sets the canvas capture zoom, in pixels per canvas unit. One means actual size, the canvas as it looks at its default zoom.

With a fixed resolution a new zoom resizes the region about its centre, otherwise it recomputes the resolution.

Gets or sets whether canvas images are written for every frame.

Gets or sets whether Rhino viewport images are written for every frame.

Gets or sets whether this animation writes to a folder of its own choosing rather than to one named after it underneath the global animation folder.

Gets or sets whether this animation is meant to be played as a loop.

A one-shot animation spreads its frames over the closed unit interval, so the final frame lands exactly on the final state. A cyclic animation spreads them over the half-open interval instead, so the final frame stops one step short and the loop does not stutter on a repeated frame.

Gets or sets whether viewport captures include the world axes icon.

Gets or sets whether viewport captures include the construction plane grid.

Gets or sets the intended playback duration in seconds.

Duration is not stored. It is the frame count divided by the rate, and setting it picks the frame count which comes closest at the current rate.

Gets or sets the folder this animation writes to when CustomFolder is set. Ignored otherwise, but remembered, so the choice survives a trip through the default and back.

Gets or sets the number of frames in this animation.

Gets or sets what happens to the frame images after a successful post-process.

Gets or sets the intended playback rate in frames per second.

The rate changes nothing about the images which get written, only how long they are meant to take on playback, which is why it is deliberately left out of the fingerprint: changing it must not invalidate a folder full of frames.

Gets whether a capture region has been picked or seeded.

Gets the immutable identity of this animation. Names are for humans, this is what manifests and user interfaces use to refer to a specific animation.

Gets the number of images this animation actually writes.

A looping animation writes one fewer than its frame count. Its first and last frames are the same picture — that is what makes it loop — so the last one is simply not written, and playback wraps from the second to last frame back to the first in a single step.

Stopping one step short by resampling instead would not work: an object with exactly as many states as there are frames would have to squeeze them all into one step fewer, which visits one state twice somewhere in the middle. The stutter is not removed by that, only moved.

Gets whether this animation drives nothing and has had none of its settings touched, which makes it a placeholder rather than something a document should be made to remember.

The name and the id are not part of the test. A fresh animation is named after whatever document it turned up in, and renaming a thing which still animates nothing is not a reason to keep it. Neither is the viewport name, which the window writes for itself rather than taking from the user.

Anything else the window sets without being asked to must be left out of the comparison as well, or a placeholder stops looking like one the moment it is displayed and starts being saved.

Compared against a newly built animation rather than against a list of literals, so the defaults are stated in one place. A setting added to this class does have to be added to the comparison below, or an animation carrying it will pass for empty.

Gets or sets the animation name.

Gets or sets what is made out of the frames once a run has written all of them.

This is declared before a run rather than chosen after one, so that starting a long animation and walking away still ends with a video. It runs only when the run completed: a cancelled run leaves a gap in the sequence, and every encoder would stop at that gap and silently produce a short film.

Gets the folder this animation actually writes to.

Unless a custom folder is set this follows the animation name, so renaming an animation moves where its images go. Frames already written stay where they were, under the old name, and are no longer found by a resume.

Gets or sets whether viewport captures omit the viewport background.

Gets or sets the viewport capture height in pixels.

Gets or sets the name of the Rhino viewport to capture. An empty name means whichever viewport is active when the animation runs.

Gets or sets the file name template for viewport captures. See FormatFileName(string, int).

Gets or sets the viewport capture width in pixels.

Add a binding for an object, unless one already exists.

Compose the full path of the canvas capture for a frame.

Gets whether an object is animated by this animation.

Seed the capture region if none has been picked, framing every object in the document with some room to spare. A document without objects gets a region the size of the resolution at the current zoom, sitting at the origin.

Compose a fingerprint of every setting which affects the images this animation writes. A resumed animation compares this against the fingerprint recorded in the output folder: if the two differ, the frames already on disk came from a different animation and cannot be mixed with new ones.

Deliberately excluded are the animation name and the binding order, neither of which changes a single pixel.

Insert a frame index into a file name template. The longest run of hash characters in the template is replaced with the zero padded frame index, so 'frame####.png' becomes 'frame0042.png'. A template without hashes gets the index inserted just before its extension instead, so no template can silently write every frame to the same file.

Frame a target rectangle with the capture region. With a fixed resolution this means centring on the target and picking the zoom at which it just fits, since the region's own size is spoken for. Otherwise the region simply becomes the target.

Remove the binding targeting an object.

Resolve all animatable objects driven by this animation. Bindings which are disabled, missing, or attached to objects which cannot currently animate are left out.
Resolve every binding which is going to take part, together with the object it drives, so a run can animate between the limits the binding actually holds.

This method is called whenever the instance is required to serialize itself.

Suggest a frame count which visits every distinct state of every binding. The suggestion is the largest state count among all bindings, clipped to the allowed frame range. Returns the current frame count if no binding can say.

Returns a string that represents the current object.

Compose the full path of the viewport capture for a frame.