Package Jitter

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.

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]
read-only

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]
read-only

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]
read-only

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]
read-only

Path length (default = 0.)

loop[int]

Path animation loop method (default = 1). Possible values:

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

outmatrixname[symbol]
read-only

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]
read-only

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

Below is a list of attributes shared by all objects. If you want to change one of these attributes for an object based on the object box, you need to place the word sendbox in front of the attribute name, or use the object's Inspector.

annotation[symbol]

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

background[int]: 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]: 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]: 0

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

jspainterfile[symbol]

JS Painter File

patching_rect[4 floats]: 0. 0. 100. 0.

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

position[2 floats]
write-only

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]: 0

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

presentation_rect[4 floats]: 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]
write-only

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]
write-only

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[4 floats]

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

textjustification[int]

Sets the justification for the object's text. 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

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

Arguments:
  • values [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.

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

closepath

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

delete

Delete the point at index

Arguments:
  • index [int]

edit

Edit the point at index

Arguments:
  • index [int]
  • values [list]

edithandle

Edit the point handle at index

Arguments:
  • index [int]
  • values [list]

eval

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

Arguments:
  • parameter [float]

evallength

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

Arguments:
  • length-parameter [float]

evaltime

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.

Arguments:
  • time [float]

gethandle

Get handle values at index and output through dump outlet.

Arguments:
  • index [int]

getpoint

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

Arguments:
  • index [int]

insert

Insert a new point at index

Arguments:
  • index [int]
  • values [list]

next

Advance the path animation to the next point.

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.

prev

Rewind the path animation to the previous point

settime

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

Arguments:
  • index [int]

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