API Introduction¶
Eddy provides APIs in multiple languages, however since Eddy is a node-based system much of the API is identical between different languages. This page describes the API features that are shared between APIs.
Language specific APIs can be found as follows:
Descriptions of the nodes available in the API can be found here:
Dependency graph¶
The dependency graph is the core of the Eddy API. By connecting nodes together in the dependency graph it is possible to create compositing networks, create simulation elements that perform substepping on their inputs, and create scenes to be rendered.
The dependency graph is essentially a data flow graph. Nodes have input plugs and output plugs, and the output plugs of nodes can be connected to the input plugs of other nodes to pass data through the graph. When the graph is evaluated, only the nodes that are required to produce the requested output will be evaluated. Simulation nodes can perform sub-stepping, evaluating their inputs repeatedly at multiple times to step the simulation forward.
In addition to plugs, nodes also have properties. A property is a simple value, that can also optionally be keyframed. A property can be exposed and overridden by an input plug, simply by creating an input plug with the same name as the property. A property can also be exposed as an output from the node, simply by creating an output plug with the same name as the property. Finally it is possible to pass-through an input plug, simply by adding an output plug with the same name as the input plug.
Enumeration types¶
The Eddy API uses simple string values for various enumerated types. These strings are used in the C API, the Python API, and for node properties.
The following are a list of all the enumeration types used in Eddy. The value in the name column should be passed as a string to the appropriate API functions.
Node data types¶
The following is a list of all the data types that can be passed between nodes with plug connections, or used as node properties.
Name |
Details |
---|---|
Float |
|
Double |
|
Int |
|
Bool |
|
V2f |
Two component floating point vector. |
V2i |
Two component integer vector. |
V3f |
Three component floating point vector. |
V3i |
Three component integer vector. |
V4f |
Four component floating point vector. |
V4i |
Four component integer vector. |
Color3f |
Color with floating point red, green, and blue channels. |
M44f |
A 4x4 transformation matrix. |
Quatf |
Quaternion. |
Box3f |
Axis aligned bounding box. |
String |
|
Camera |
|
Field |
|
Emitter |
|
Collider |
|
Holdout |
|
DenseVolumeChannelSet |
|
SparseVolumeChannelSet |
|
ChannelSet |
A group of named field channels. |
PointLight |
|
SpotLight |
|
QuadAreaLight |
|
EnvironmentLight |
|
DirectionalLight |
|
RenderVolume |
|
RenderScene |
A description of a scene which can then be rendered. |
RenderData |
All the information required to render, i.e. scene, camera, settings. |
VisualizerData |
|
Mesh |
A mesh contains vertices, polygons, normals, and other data channels. |
CompoundMesh |
A compound mesh consists of multiple child meshes each with their own transform. |
FloatRamp |
Provides a mapping from one floating point number to another. |
Float4Ramp |
Provides a mapping from one floating point number to a vector of four floating point numbers. |
Image |
A 2D image. |
DeepImage |
A deep image. |
ImageGenerator |
An object that can be called to generate an image. |
DeepImageGenerator |
An object that can be called to generate a deep image. |
ChannelList |
Describes a list of channels. |
InstanceCallsheet |
Provides a list of uniquely identified InstanceItems to node ( eg.: ParticleInstanceNode ). |
InstanceCollection |
Contains a collection of instance assemblies for meshes and fields. |
InstanceItem |
A base type used to wrap more complex types like meshes, fields, particles for instancing. |
Instancer |
An instancer that generates instances and stores them in a InstanceCollection. |
ParticleSystem |
A particle system |
Bounds |
|
Renderable |
|
ShaderNetworkOutput |
|
Texture |
|
Material |
|
Any |
On a plug this indicates that the plug can be connected to any other plug, and can accept any data type. |
Invalid |
Should not be found, indicates an error has occurred. |
Field plug types¶
Field plugs have an additional field type, which can be used to constrain what types of field can be connected to the plug.
Name |
Description |
---|---|
Unknown |
The field plug can be connected to any other type of field plug. |
Scalar |
The field plug can only be connected to other scalar field plugs. |
Vector |
The field plug can only be connected to other vector field plugs. |
None |
The plug is not a field plug. |
Evaluation Modes¶
Output plugs can specify their evaluation mode, which controls how the Evaluator will calculate its output value when required.
Name |
Description |
---|---|
PassThrough |
Determines plug output by copying directly from a property or input plug. |
Simple |
Calls the node evaluate function one time only with all inputs provided. |
MultipleTime |
Calls the node evaluation_time_offsets function to get a list of time offsets. For each offset pre_evaluate will be called to allow the required inputs to be specified, and then the node evaluate function will be called for each time. If the offset is zero the full step context will be used, for non-zero offsets the context will be set to the specified offset time. |
PreEvaluationLoop |
Runs the full pre-evaluation loop. On each iteration, the pre_evaluation_requested_values function will be called first, followed by pre_evaluate which can modify the context, and then finally the node evaluate function. The loop will terminate when the end time of the full step has been reached. |
File Error Modes¶
Cache loaders can specify the behavior when there is an error loading a file.
Name |
Description |
---|---|
Error |
Eddy will produce an error and stop further graph execution. |
Empty |
An empty output will be generated with the channels specified in the loader. |
Hold |
The nearest frame of the start or end of the file sequence will be loaded. |
Vector Transform Types¶
Used to specify how vector fields should behave under transformations. See Vector Channel Transformations for more information.
Name |
Description |
---|---|
Vector |
This is the default transformation type. The vector value is rotated and scaled by any applied transformation. Velocity, force, and direction channels should all transform with this method. |
Normal |
Normal vectors are affected by rotations in the same way as regular vectors, but they behave differently when scaled. This is used for normal vector channels that are voxelized from meshes by the MeshToVolumeRefLabel node, or for the gradient calculated by the FiniteDifferentRefLabel node. |
Coordinate |
Coordinate vectors are not affected by transformations. This should be used for color channels, texture coordinate channels etc. |
Compositing Modes¶
Used by the Composite field to specify how the inputs should be combined.
Name |
Description |
---|---|
Add |
Adds the fields together. |
Sub |
Subtracts the second, third, etc. fields from the first field. |
Min |
Takes the minimum value of all the fields. |
Max |
Takes the maximum value of all the fields. |
Mul |
Multpilies the fields together. |
Div |
Divides the first first by the second, third, etc. fields. |
Interpolation Types¶
Specifies how discrete voxel data should be interpolated during sampling operations. See Interpolators for more details about the available interpolators.
Name |
Description |
---|---|
TriLinear |
This is the simplest and fastest interpolator. It is the default and is the recommended safe choice. |
BSpline |
This is a type of tricubic interpolator which is slightly faster than the other tricubic interpolators, but introduces a lot of smoothing to the channel. |
TriQuadratic |
This is a type of triquadratic interpolator which is faster than tricubic interpolators. It has a good balance between performance and quality. |
TriCubic |
This is standard tricubic interpolation. The method is slower than trilinear but produces a smoother result without the excessive smoothing of B-Spline. Tricubic can overshoot data. |
MonotonicTriCubic |
This is a version of tricubic interpolation that is monotonic and thus will not overshoot data. |
HighOrder |
This is an Eddy custom high order interpolator. It is faster than Tricubic and produces results smoother than trilinear but not as smooth as Tricubic. This method typically does not overshoot data. |
ClampedHighOrder |
This is a version of the High order interpolator that sacrifices some smoothness in order to guarantee that it never overshoots data. |
Script Language Types¶
Name |
Description |
---|---|
Python |
Python script, or more specifically EddyScript. |
Cpp |
C++ script. |
Field Types¶
Name |
Description |
---|---|
Scalar |
Scalar field, e.g. a fog volume. |
ScalarIso |
Scalar iso-surface field, iso-value represents a surface but field values are not necessarily distances. |
ScalarSdf |
Scalar SDF field. Values are expected to be correct distances. |
Vector |
Vector field, value transforms as a regular vector. |
Normal |
Vector field, value transforms as a normal vector. |
Coordinate |
Vector field, value does not change under transformations. |
VectorComposite |
Vector field, value can have a more complicated transformation behavior, typically obtained when compositing different vector field types. |
Scalar Field Types¶
Name |
Description |
---|---|
Standard |
Scalar field, e.g. a fog volume. |
Iso |
Scalar iso-surface field, iso-value represents a surface but field values are not necessarily distances. |
Sdf |
Scalar SDF field. Values are expected to be correct distances. |
Filter Function Modes¶
Name |
Description |
---|---|
Box |
Calculates a 3x3x3 Box blur |
Gaussian |
Calculates a 5x5x5 Gaussian |
Finite Difference Modes¶
Name |
Description |
---|---|
Gradient |
Calculates the gradient of a scalar field, result will be a vector. |
Curl |
Calculates the curl of a vector field, result will be a vector. |
Laplacian |
Calculates the Laplacian of a scalar field, result will be a scalar. |
Divergence |
Calculates the divergence of a vector field, result will be a scalar. |
Image Formats¶
Name |
Description |
---|---|
FloatRGB |
A three channel color image stored in RGB order. |
FloatRGBA |
A four channel color image with alpha stored in RGBA order. |
FloatY |
A single channel luminance image. |
FloatRGBARAGAB |
A six channel color image with colored alpha, stored in R,G,B,AR,AG,AB order. |
Math Field Modes¶
Name |
Description |
---|---|
Absolute |
Returns a scalar field containing the absolute value of the scalar input. |
Magnitude |
Returns a scalar field containing the vector magnitude of the vector input. |
Sign |
Returns a scalar field containing the sign (i.e. +1.0 or -1.0) of the scalar input. |
Smoothstep |
Returns a scalar field containing the smoothstep function applied to the scalar input. |
Pow |
Returns a scalar field containing the squared value of the scalar input. |
Normalize |
Returns a vector field containing the normalized vector input. |
VecCompX |
Returns a scalar field containing the X component of the vector input. |
VecCompY |
Returns a scalar field containing the Y component of the vector input. |
VecCompZ |
Returns a scalar field containing the Z component of the vector input. |
Offset Lookup Field Modes¶
Name |
Description |
---|---|
Trace |
Takes n steps along the vector field and returns the input field value at the final sample location. |
Remap |
Samples the vector field at the current location, using it as coordinates to sample the input field. |
MotionBlur |
Takes multiple steps along the vector field, samples the input field and averages the samples. |
Vector Math Field Modes¶
Name |
Description |
---|---|
Dot |
Returns a scalar field containing the dot product between two vector inputs. |
Cross |
Returns a vector field containing the cross product between two vector inputs. |
Emission Modes¶
Name |
Description |
---|---|
Set |
Sets the value of the target channel to that of the input channel. |
Add |
Adds the input channel value to the target channel. |
Sub |
Subtracts the input channel value from the target channel. |
Min |
Sets the target channel value equal to the minimum of the target and the input channels. |
Max |
Sets the target channel value equal to the maximum of the target and the input channels. |
Mul |
Sets the target channel value equal to the product of the target and the input channels. |
Div |
Sets the target channel value equal to the target divided by the input. |
GuideWeak |
Guides the target channel value towards that of the input in a weak (non-strict) manner. |
GuideStrong |
Guides the target channel value towards that of the input in a strong (strict) manner. |
VectorBlend |
Guides the target vector channel towards that of the input vector channel in a user controllable and non-trivial manner. |
Color spaces¶
The following are the available built-in color spaces. Additional color spaces can be registered by user python scripts, these color spaces will then become available everywhere the built-in color spaces can be used.
Name |
Description |
---|---|
XYZ |
The standard CIE XYZ color space. |
xyY |
The standard CIE xyY color space, where x and y are the chromaticities and Y is the luminance. |
Yxy |
The standard CIE xyY color space, but with a different order for the components. |
sRGB |
The sRGB color space. |
AdobeRGB |
The Adobe RGB (1998) color space. |
WideGamutRGB |
The Adobe Wide Gamut RGB color space. |
LMS |
The LMS color space, based on the response of the three types of cones of the human eye. |
Light falloff modes¶
Name |
Description |
---|---|
None |
No falloff, light intensity remains constant regardless of distance. |
Linear |
Intensity decreases linearly as distance increases. |
Quadratic |
Intensity decreases with the square of the distance. This is the physically correct behavior. |
Cubic |
Intensity decreases with the cube of the distance. |
Camera projection types¶
Name |
Description |
---|---|
Perspective |
A standard perspective projection. |
SphericalLatitudeLongitude |
Latitude-longitude environment map projection. |
Fisheye180 |
Fisheye projection for 180 degrees, i.e. a hemisphere. |
Fisheye360 |
Fisheye projection for 360 degrees, i.e. the full sphere. |
Orthographic |
A standard orthographic projection. |
Integrator types¶
Name |
Description |
---|---|
Raymarching |
Raymarching integrators step along the ray using the volume feature size as the step length. This is therefore not supported for implicit volumes with a zero feature size. Raymarching also introduces a small bias. |
Tracking |
Tracking integrators take random length steps along the ray, and can be used with any volume including implicit volumes. |
Transmittance integrator types¶
Name |
Description |
---|---|
Raymarching |
Raymarching integrators step along the ray using the volume feature size as the step length. This is therefore not supported for implicit volumes with a zero feature size. Raymarching also introduces a small bias. |
Tracking |
Tracking integrators take random length steps along the ray, and can be used with any volume including implicit volumes. |
DeltaTracking |
Delta tracking integrators can be faster than the other tracking integrators, however only provide a binary estimate of the transmittance, so may be more suitable for secondary rays. |
Volume settings modes¶
Name |
Description |
---|---|
Global |
Use the global default settings from the render node. |
CustomAutomatic |
Analyze this volume and automatically choose unique settings for this particular volume. |
CustomManual |
Manually specify the volume integrator settings for this particular volume. |
Motion output types¶
Name |
Description |
---|---|
Forward |
Calculate forward motion vectors, i.e. from the current frame towards the next frame. |
Backward |
Calculate backward motion vectors, i.e from the previous frame towards the current frame. |
Instant |
Calculates motion vectors using the instantaneous motion at the current frame. |
Pixel filter types¶
Name |
Description |
---|---|
Box |
A simple box filter, this is usually a poor choice in practice. |
Triangle |
A triangle filter, produces better results than the box filter. |
Gaussian |
A Gaussian filter, this is a good choice in practice. Can have slight blurring. |
BlackmanHarris |
A Blackman-Harris filter, an alternative to the Gaussian filter. |
MitchellNetravali |
A Mitchell-Netravali filter, this can sharpen the image although with the risk of ringing artefacts. |
Lanczos |
A Lanczos filter, also known as a sinc filter, this can sharpen the image although with the risk of ringing artefacts. |
Render target output types¶
Name |
Description |
---|---|
Default |
Uses the default output type. For most predefined outputs this will be ‘Normal’, but some will require a different type which this will choose automatically. |
Normal |
The output will store color or radiance values, this is the standard type used by most outputs. |
Unoccluded |
The output will store unoccluded radiance values, i.e. with shadowing disabled. |
Shadow |
The output stores the amount of shadow at each pixel. This is scaled from 0 to 1. |
ShadowDifference |
The output stores the shadow difference at each pixel, i.e. the amount that would need to be subtracted from an image without shadows to get the image with shadows. |
Raw |
The output stores raw non-color values. This disables some color processing that would usually be done, particular for deep data output. Used by utility outputs that are not returning a color. |
Opacity |
The output stores the opacity of each pixel. This provides the full RGB opacity, compared to the alpha channel which has just one component. |
Render target output modes¶
Name |
Description |
---|---|
Default |
Uses the default output mode. For most predefined outputs this will be ‘Standard’, but some will require a different mode which this will choose automatically. |
Standard |
The standard mode is used by most color or radiance outputs, the colors from multiple camera rays will be averaged together. |
Sum |
Instead of averaging the pixel values will be accumulated. For example this is used by some statistics outputs which count the rays. |
AlphaWeighted |
The final pixel value is weighted by the alpha value of its samples. This is useful when the image contains volumes or other transparent objects, for example with a velocity output this will produce the average velocity of all the volume samples at a pixel. |
Closest |
The pixel stores only the result of the closest sample to the camera, all other samples are discarded. |
Furthest |
The pixel stores only the result of the furthest sample from the camera, all other samples are discarded. |
Render target output holdout modes¶
Name |
Description |
---|---|
Default |
Uses the default holdout mode. For most predefined outputs this will be ‘Exclude’, but some will require a different mode which this will choose automatically. |
Exclude |
Holdouts are excluded from the image, this is the normal behavior. |
Include |
Holdouts will be included in the image, just as any other object. |
Extract Bounds Modes¶
Name |
Description |
---|---|
RootBounds |
Extracts only the overall root bounding box from the field or mesh. |
SubBounds |
Extracts the detailed sub-object bounding boxes, e.g. the sparse simulation bounds or individual mesh bounds. |
Sky Model types¶
Name |
Description |
---|---|
Physical |
This calculates the sky color by tracing rays through a model of the atmosphere. It therefore produces correct results even when the sun is very low, and can also calculate the sky as it appears at different heights above ground. |
PhysicalSpectral |
This is similar to the physical model, but colors are calculated using a full spectral simulation instead of just using an RGB triple. The result is usually slightly better than the physical model, although it does take a bit longer to calculate. |
PreethamShirleySmits |
This is an approximate model that attempts to match a physical model as closely as possible. It does not have as many parameters as a physical model, and although it is only approximate it is very fast to calculate. |
CIEStandard |
This provides the CIE standardized sky models. These are a variety of luminance only (i.e. monochrome) equations that model various sky conditions. |
CIETraditionalOvercast |
The CIE Traditional Overcast sky model approximates the luminance only (i.e. monochrome) of an overcast sky. |
Sky Sun direction modes¶
Name |
Description |
---|---|
Angles |
The sun direction is specified using zenith and azimuth angles. |
Direction |
The sun direction is specified directly as a vector. |
TimeAndPlace |
The sun direction is specified by providing the time and place on the earth. |
Camera shutter modes¶
Name |
Description |
---|---|
Backward |
The camera shutter is open before the frame time. |
Center |
The camera shutter is open on an interval centered on the frame time. |
Forward |
The camera shutter is open after the frame time. |
Instance item types¶
Name |
Description |
---|---|
Field |
This item represents a field. |
Mesh |
This item represents a mesh. |
ChannelSet |
This item represents a channel set. |
CompoundMesh |
This item represents a compound mesh. |
Instancer |
This item represents an instancer, enabling recursive instancing. |
Variant |
This item represents a variant, allowing random selection of its inputs. |
Callback |
This item represents a callback that will be executed when the instancer is building the instances. |
VolumeCache |
This item represents a volume cache that allows instantiation and manipulation of VDB cache sequences. |
Instance time offset modes¶
Name |
Description |
---|---|
None |
The instance time offset is determined by a global random offset and no per instance control is used. |
Relative |
The instance time offset is shifted relative to the global random offset by a per instance attribute. |
Absolute |
The instance time offset is controlled by a per instance attribute. |
Instance callsheet modes¶
Name |
Description |
---|---|
Random |
The instance callsheet selection is determined by a per instance random variable. |
Channel |
The instance callsheet selection is determined by a per instance particle attribute. |
Instance rotation modes¶
Name |
Description |
---|---|
Random |
The instance rotation determined by a per instance random variable. |
Channel |
The instance rotation determined by a per instance particle attribute. |
Instance scale modes¶
Name |
Description |
---|---|
Random |
The instance scaling determined by a per instance random variable. |
Channel |
The instance scaling determined by a per instance particle attribute. |
Instance Field Modes¶
Name |
Description |
---|---|
Add |
Overlapping instance fields will be added together. |
Minimum |
The minimum will be taken of all the overlapping instance fields. |
Maximum |
The maximum will be taken of all the overlapping instance fields. |
Average |
The average will be taken of all the overlapping instance fields. |
Instance Particle Modes¶
Name |
Description |
---|---|
Random |
The attribute will be controlled by a random value for each particle. |
Channel |
The attribute will be controlled by a per particle attribute. The E_ParticleExpression can be used to set values explicitly. |
Particle Visualizer Modes¶
Name |
Description |
---|---|
Uniform |
The attribute will be controlled by a uniform value for each particle. |
Channel |
The attribute will be controlled by a per particle attribute. The E_ParticleExpression can be used to set values explicitly. |