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:

Node Reference

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.