Path Nodes

	Path Loader	Provides a path that was loaded from a file.
	Select Path Segment	Selects segments of a given Path.
	Subdivide Path	Subdivides a Path into equally long parts.
	Path Axis	Adds the Transformation of a position on a given Path to the Hierarchy.
	Path Matrix	Outputs the Transformation of a position on a given Path.

The Path Nodes handle 3D Paths imported from other programs. They can be ultimately used by several Nodes that either render them (Geometry Renderer or Path Arrow) or use them for positioning (Path Axis or Particle System).

Path Providers

The Path Loader, Path Segment and Subdivide Path Nodes all Output a Path for further usage in the Scene Logic. Their Inputs depend on the chosen Source Property Group. You can load paths or modify them by chosing segments or performing a subdivision.

Select Path Segment

The Select Path Segment property group returns a path with only the chosen segments. The range is defined by the indices of the First- and LastSegment.

The source path can be either a Path Loader or a Path Property.

Subdivide Path

Subdivide Path takes a path and re-arranges its points so that even distances between them are created. This is mainly used to create a constant speed along the whole path - e.g. for animations along it. You can see a simple visualization of the original path and the result in the image below.

Property Groups

Each Path Provider passes a Path to the consisting node. Except on the Path Provider Node there are only two available Property Groups.

Path Loader

The Path Loader will load a path that was saved in a Ventuz Path File (.VPATH}) or an .SVG file. To import a Path to Ventuz and thus create a Ventuz Path File please see the Geometry Import Live Node.

Imported paths have points in 3D space and segments as defined in the software they are coming from. Paths from SVG Files have points in 2D space and each segment represents a <path>-element in that SVG File. All non-path elements of the SVG are ignored.

The units given in the loaded path file will by default directly apply to Ventuz units when not applying any scaling to the path.

If the AutoUpdate flag is turned on the Path Loader will automatically update the node whenever the loaded path file was changed.

The Path Loader provides several Presets for faster and easier usage.

Path Property

The Path Property is used to reference any path that is present in the Scene's Logic. Using this option enables you to first apply any kind of logic to the given path before using it on the corresponding node.

Path Axis

Path Axis works similar to the Axis in that it provides the upcoming subtree of the hierarchy with a transformation. You can again choose the Source of the Path which can either be a directly loaded path or a path from the scene's logic.

With the Segment property you can choose the used segment for the evaluation. The Position is used to determine the current point on that segment in percent. You can also turn on and of whether to use the current tangent as a rotation with the WithDirection boolean. If ConstantVelocity is enabled, the position on the path is calculated such that it is proportional to the Position property change.

Path Matrix

Path Matrix outputs the transformation matrix on the given point. Segment again chooses the used segment for that evaluation and Position determines the exact point on that segment. The Source can be either a Path Loader or a Path Property bound to any other Path Property in the Scene's Logic.

You can then further use the transformation matrix in your scene's logic before applying it somewhere. Additionally the node returns the position as XYZ values.

Ventuz Path File Specification

You can create custom .VPATH files in other software by building a JSON that follows the specifications defined in this chapter.

Ventuz stores 3D paths in a JSON file with .vpath extension. A Ventuz Path consists of one or more segments, each of which is a path of spline curves that can be open or closed.

What's following is a pseudocode description of the used JSON format in a C-link language that should be easy to translate to the language of your choice:

/* 
* VPATH JSON file format (pseudocode), Version 1.0
* Copyright 2019 Ventuz Technology AG
*/

// Top-level JSON structure
struct VPathFile
{
    // this needs to come first for Ventuz to identify the file format
    string @ = "http://ventuz.com/SplinePath/1.0";
   
    PathDef Path;
}

// Each path object consists of a number of independent segments,
// e.g. the inner and outer outline of the letter "A".
struct PathDef
{
    PathSegment[] segments;
}

// Each path segment consists of a number of control points and 
// whether the path is closed (the last point loops back to the first).
struct PathSegment
{
    PathPoint[] points;
    bool isClosed;
}

// Each point consists of a number of attributes
struct PathPoint
{
    // Position of the point. Most important.
    Vector3WithTangents pos;
    
    // "Up" auxiliary vector. Needed to construct a proper matrix from
    // the position and the spline direction. Make sure this is never 
    // collinear with the spline direction, e.g. if your spline is in the XY
    // plane, just use x=0, y=0, z=1 for "up".
    Vector3WithTangents up;
    
    // Point color. X is red, Y green, Z blue and W is alpha. Used in 
    // the Geometry Renderer.
    Vector4WithTangents color;
    
    // Point "size". Can be used in particle systems.
    ValueWithTangents size;
}

// 4-component vector structure
struct Vector4WithTangents
{
    ValueWithTangents x,y,z,w;
}

// 3-component vector structure
struct Vector3WithTangents
{
    ValueWithTangents x,y,z;
}

// Value with tangents, a.k.a explicit derivatives 
struct ValueWithTangents 
{
    // Actual value
    double value;
    
    // "Left" tangent, a.k.a. the derivative of the function towards the preceding point
    // (ignored for first point of open path)
    double tanL; 
    
    // "Right" tangent, a.k.a. the derivative of the function towards the succeeding point
    // (ignored for last point of open path)  
    double tanR;
}

Notes:

• Non-specified fields will be filled with zeroes
• Extraneous fields not specified in the file format will be ignored
• The tangents specify the derivative of the spline function assuming the difference between the points' t is 1.0. If you deal with Bezier control points p0, p1, p2, and p3, convert to two spline points a and b component-wise like this:

  a.value = p0;
  a.tanR = (p1-p0)*3;
  b.tanL = (p2-p3)*3;
  b.value = p3;
  

Likewise, a linear spline segment is best expressed as a.tanR = b-a; b.tanL = a-b; Leaving the tangents at zero will result in a linear but poorly weighted segment affecting the speed along the resulting spline.