jit.path
Jitter Reference
Open Help

jit.path

Evaluates a series of N-dim points as a path

Description

The jit.path object takes a series of N-dimensional points retrieves interpolated values based on an input parameter. It is useful for creating user interfaces for parameter morphing.

Examples

Evaluates a series of N-dim points as a path

Discussion

The jit.path object performs this interpolation using either linear or Hermite spline interpolation. The Hermite splines are automatically calculated using the Catmull-Rom method, which creates a single tangent for each point. The interpolated values are retrieved based on an input parameter. There is also the option of outputting a matrix out the second outlet filled with the interpolated values, with the number of planes equal to the dimension of the path.
Points are added to the path either with messages, or by passing in a 1D matrix of point values. A 2D matrix will be output containing the path points in the first row, and the automatically calculated tangents in the second row.
The length of the path can be calculated by treating the first three dimensions as x/y/z position values. The path can optionally be evaluated based on the length.

Attributes

autohandles [int]

Enable the calculation of handle values every time the path is edited (default = 1).

closed [int]

g/s(get)

Indicates the path is closed (first and last points are equal).

dim [int]

Path dimension and number of planes in point and eval matrices (default = 0).

duration [float]

g/s(get)

Path duration in seconds (default = 0.)

evalmatrixmode [symbol]

Determines how the eval-matrix is evaluated (default = eval).

Possible values:

'eval' ( Normalized by pointcount )
'evallength' ( Normalized by pathlength )

evalmatrixname [symbol]

g/s(get)

The eval matrix name (default = UID). This is a read-only attribute and is useful in conjunction with the calc_evalmatrix message when accessing jit.path in javascript.

evalmatrixsize [int]

The size of the eval-matrix (default = 100).

grain [int]

Time grain used when animating in milliseconds (default = 50).

interpmode [symbol]

Path interpolation method (default = linear).

Possible values:

'linear' ( Linear interpolation )
'spline' ( Hermite interpolation )

length [float]

g/s(get)

Path length (default = 0.)

loop [int]

Path animation loop method (default = 1).

Possible values:

0 = 'off'
1 = 'on'
2 = 'palindrome'

outmatrixname [symbol]

g/s(get)

The point output matrix name (default = UID). This is a read-only attribute and is useful in conjunction with the calc_outmatrix message when accessing jit.path in javascript.

play [int]

Enable path animation (default = 0).

pointcount [int]

g/s(get)

Number of path points (default = 0).

rate [float]

Animation rate value (default = 1.)

thru [int]

Output point matrix receiving input matrix (default = 1).

time [float]

Current path time value (default = 0.)

timemode [symbol]

Determine how time values added to the path (default = relative).

Possible values:

'absolute' ( Time value is set to argument )
'relative' ( Time value is set to argument plus previous time value )

usetime [int]

Determine if first path dim is used as time value (default = 0).

Common Box Attributes

annotation [symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background [int] (default: 0)

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color [4 floats]

Sets the color for the object box outline.

fontface [int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic

Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname [symbol]

Sets the object's font.

fontsize [float]

Sets the object's font size (in points).

Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden [int] (default: 0)

Toggles whether an object is hidden when the patcher is locked.

hint [symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick [int] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation [int] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 0. 0. 0. 0.)

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect [4 floats]

g/s(set)

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size [2 floats]

g/s(set)

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor [float]

Sets the color for the object's text in RGBA format.

textjustification [int]

Text Justification

Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname [symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

Messages

bang

Output the point matrix

append

Arguments

values [list]
Append point values to the end of the path. If dim is 0, it is set to length of arg list.

calc_evalmatrix

Calculate the eval matrix by filling with the evaluated values of the path. The matrix is 1D, the size is equal to the evalmatrixsize, and the planes are equal to path dim. Useful in conjunction with the evalmatrixname attribute when accessing jit.path in javascript.

calc_outmatrix

Calculate the point output matrix by filling with the path point and handle values. The matrix is 2D with the size is equal to number of points, and planes equal to path dim. Useful in conjunction with the outmatrixname attribute when accessing jit.path in javascript.

closepath

Close the path by adding a point to the end equal to the first point.

eval

Arguments

parameter [float]
Evaluate the path using parameter , (between 0. and 1.) and output the interpolated values.

evallength

Arguments

length-parameter [float]
Evaluate the path using the length-parameter (between 0 and pathlength) and output the interpolated values.

evaltime

Arguments

time [float]
Evaluate the path using time (between 0 and duration) and output the interpolated values. The usetime attribute must be set to 1, causing the first dim of the path to be treated as time values.

delete

Arguments

index [int]
Delete the point at index

calchandles

Calculate the path handles of each point in the path using the Catmull-Rom method. This will overwrite any previously stored handles.

clear

Remove all points from the path

edit

Arguments

index [int]
values [list]
Edit the point at index

edithandle

Arguments

index [int]
values [list]
Edit the point handle at index

gethandle

Arguments

index [int]
Get handle values at index and output through dump outlet.

getpoint

Arguments

index [int]
Get the point values at index and output through dump outlet. point .

insert

Arguments

index [int]
values [list]
Insert a new point at index

outputeval

Output a matrix from the second outlet, filled with the evaluated values of the path. The matrix is 1D, the size is equal to the evalmatrixsize, and the planes are equal to path dim.

next

Advance the path animation to the next point.

prev

Rewind the path animation to the previous point

settime

Arguments

index [int]
Set time at index . If necessary, the path will be resorted prior to evaluation.

sorttime

Sort path based on time values

start

Start path animation

stop

Stop path animation

See Also

Name Description
jit.anim.path Evaluate a path of 3D transform points
jit.gl.path Generate and render a path in OpenGL