reference

cosm.master stores global state for a world (including main camera navigation), which can be used locally or broadcast to a remote patch. Camera navigation is also accessible via cosm.query under the symbol 'camera'.

Messages

message	arguments	meaning
bang		output current position and orientation
sync		outout camera focus, lens angle, stereo mode and spread
halt		stop moving and turning; equivalent to (move 0 0 0) and (turn 0 0 0).
home		return to origin. equivalent to (position 0 0 0)

Attributes

attribute	arguments	meaning
accumulate	0/1	whetehr velocity and angular velocity is retained between frames (default on)
enable	0/1	if 0, bangs will be ignored.
fullscreen	0/1	control fullscreen state of window(s)
position	x y z	set position in world coordinates
quat	w x y z	set absolute orientation in world refernce frame; quaternion format
rotate	angle x y z	set absolute orientation in world reference frame; axis/angle format
turn	azimuth elevation tilt	set angular velocity in object-local reference frame
move	x y z	set velocity in object-local reference frame
focus	float	current focal point (for stereographics)
spread	float	current eye separation (for stereographics)
stereo	0/1	enable/disable stereo rendering
lens_angle	float	field of view for rendering

cosm.render

cosm.render manages state to control jit.gl.render and jit.window, including stereographics. The first outlet should be connected to jit.gl.render, the second outlet to jit.window. The third outlet bangs once per render (in stereo mode, twice per frame). Typically a cosm.master's first outlet connects to a cosm.render. For distributed rendering, the connection between cosm.master and cosm.render can be over a network.

Messages

message	arguments	meaning
bang		triggers one frame of rendering

Attributes

attribute	arguments	meaning
fullscreen	0/1	control fullscreen state of window
enable	0/1	if 0, bangs will be ignored.
position	x y z	set position in world coordinates
quaternion	w x y z	set absolute orientation in world refernce frame; quaternion format
focus	float	current focal point (for stereographics)
spread	float	current eye separation (for stereographics)
stereo	0/1	enable/disable stereo rendering
lens_angle	float	field of view for rendering

cosm.World

cosm.world can be used to set global parameters of the rendered world.

Attributes

attribute	arguments	meaning
enable_nhood	0/1	enable or disable collision testing
size	int int int	size of the world (diameter) in OpenGL units. Non-cubic worlds are possible, but may reduce the accuracy of collision detection.
infinite	int	determine whether the world is bounded; @infinite 0 results in a space in which objects cannot leave the cuboid of +/- @size; @infinite 1 results in a space in which only objects within +/- size of the navigating camera are enabled.
audio_doppler	float	set the extremity of doppler shift (in seconds); i.e. the total delay for a sound object at @audio_far distance from the observer. Default 0.05 seconds.
audio_filter	float	set the amount of distance filtering: lowpass simulation of air absorption (default 1). Values greater than 1 will result in more extreme filtering, and may effectively cause sounds to become inaudible before reaching @audio_far. Values less than 1 will reduce the filtering effect. A value of 0 will effectively bypass filtering.
audio_near	float	set the distance (OpenGL units) at which filtering and attenuation begins (default 1). Sound sources at @audio_near or less distance will be unfiltered, unattenuated, and have only single-sample delay.
audio_far	float	set the distance (OpenGL units) at which a sound becomes inaudible (default 100). Sound sources beyond @audio_far units will be inaudible, and have delay of @audio_doppler seconds.

Cosm.nav

cosm.nav allows (bounded) six-degrees of freedom navigation of objects in a rendered scene, and supports collision detection. The first outlet reports position and orientation (rotate axis/angle) of the object. The second outlet reports collisions detected.

Messages

message	arguments	meaning
bang		output current position and orientation
halt		stop moving and turning; equivalent to (move 0 0 0) and (turn 0 0 0).
home		return to origin. equivalent to (position 0 0 0)

Attributes

attribute	arguments	meaning
accumulate	0/1	whetehr velocity and angular velocity is retained between frames (default on)
enable	0/1	if 0, bangs will be ignored.
position	x y z	set position in world coordinates
quat	w x y z	set absolute orientation in world refernce frame; quaternion format
rotate	angle x y z	set absolute orientation in world reference frame; axis/angle format
turn	azimuth elevation tilt	set angular velocity in object-local reference frame
move	x y z	set velocity in object-local reference frame
nhood	0/1	disable/enable collision detection
name	symbol	name used in collision reporting, and for cosm.query
boundmode	int	if the cosm.world is at @infinite 0: @boundmode 1 wraps objects at the world boundary, @boundmode 0 clips objects at the world boundary if the cosm.world is at @infinite 1: @boundmode 1 wraps objects at the camera position +/- world size, @boundmode 0 does not change object positions in any way.

cosm.query

Cosm.query can get and set any attribute of a named cosm.nav in the world. It is useful to handle relationships between cosm.nav objects, especially in response to collision reporting.

Note that the camera navigation itself uses a hidden cosm.nav, available to cosm.query under the name 'camera'.

Messages

message	arguments	meaning
anything	name (symbol) attribute (symbol)	retrieve any attribute of a named cosm.nav. the attribute and value is returned from the cosm.query outlet.
	name (symbol) attribute (symbol) anything	set any attribute of a named cosm.nav. the extra arguments should match the corresponding attribute setter.

Cosm.audio~

Given a position and orientation, cosm.audio~ can calculate appropriate azimuth, elevation and distance for spatialization, and perform distance cue processing to the source signal accordingly. The first outlet is the distance filtered signal, the second outlet is azimuth/elevation messages for spatializers, and the third outlet is distance from the camera. Distance filtering parameters are set globally in cosm.world.

Messages

message	arguments	meaning
bang		output current azimuth, elevation and distance
rotate		currently ignored, but will be used for directivity filtering
home		return to origin. equivalent to (position 0 0 0)

Attributes

attribute	arguments	meaning
position	x y z	set position in world coordinates
quaternion	w x y z	set absolute orientation in world refernce frame; quaternion format

cosm.ambi.encode~

Encodes a monophonic signal into an Ambisonic domain representation (output signals). Number of output signals depends on order and dimensionality of the encoding; the channel identifiers are given by the outlet tooltips. Typically many encoders can mix outputs for a single decoder, which can be conveniently achieved with send~ and receive~ sets.

ARGUMents

arguments	meaning
2D or 3D	2d or 3d encoding (default 2D)
1st, 2nd or 3rd	1st-order, 2nd-order or 3rd-order encoding. (default 1st)
radians or degrees	angle convention. default radians.

Messages

message	arguments	meaning
azimuth	float	set current azimuth
elevation	float	set current elevation
degrees		set angle mode to degrees
radians		set angle mode to radians
dump		print information about the encoder to the Max window

cosm.ambi.cloud~

Encodes grains into an Ambisonic domain representation (output signals), by granulating a specified buffer~. Uses the same distance filtering approach as cosm.audio~ and encoding mechanism of cosm.ambi.encode~ per grain. Grains can be specified by lists of 6 floats, or by 6-plane, float32, 1-D Jitter matrices. The 6 floats correspond to X, Y, Z, duration (ms), buffer~ offset (ms), and playback rate. Each grain will be scheduled at a random interval up to 2/period into the future.

Number of output signals depends on order and dimensionality of the encoding; the channel identifiers are given by the outlet tooltips. It can mix outputs with other cosm.ambi.cloud~ or cosm.ambi.encode~ obejcts for a single decoder, which can be conveniently achieved with send~ and receive~ sets.

ARGUMents

arguments	meaning
2D or 3D	2d or 3d encoding (default 2D)
1st, 2nd or 3rd	1st-order, 2nd-order or 3rd-order encoding. (default 1st)
<symbol>	name of buffer~ to granulate
int	maximum number of active grains (default 1024)

Messages

message	arguments	meaning
jit_matrix	matrix	trigger grains; the matrix must be 6-plane float32 and one-dimensional. Each cell creates a grain; the 6 floats correspond to X, Y, Z, duration (ms), buffer~ offset (ms), and playback rate.
grain	float float float foat float float	strigger a grain; the 6 floats correspond to X, Y, Z, duration (ms), buffer~ offset (ms), and playback rate.
set	symbol	change which buffer~ is being granulated
env	symbol int	change the grain window envelope; copies data from the specified buffer up to the specified sample index
period	float	set the expected update period; each grain will be scheduled for a random interval of up to twice this amount in the future. Default 25ms.
fps	float	set the period as 1/fps. Typically this should match the update rate of the incoming matrices for a smooth effect.
dump		print information about the encoder to the Max window

cosm.ambi.decode~

Decodes Ambisonic signals to a number of audio outputs (usually connected to loudspeakers). Many encoders can mix signals for a single decoder (if the Ambisonic orders/dimensions match). The speaker arrangement must be configured in cosm.ambi.decode~ for spatialization to work; the default configuration is a stereo output with front-left and front-right speakers (-/+ 45 degrees azimuth).

ARGUMents

arguments	meaning
2D or 3D	2d or 3d encoding (default 2D)
1st, 2nd or 3rd	1st-order, 2nd-order or 3rd-order encoding. (default 1st)
radians or degrees	angle convention. default radians.
int	number of speakers (output channels)

Messages

message	arguments	meaning
gain	float	set amplitude scalar for entire mix (default 1)
width	float	set mono (W) versus spatial channels mix (default equal)
weights	float array	set amplitude scalar per order (mono, 1st, 2nd, 3rd)
speaker	id (int) azimuth (float) elevation (float)	set speaker azimuth/elevation for a given outlet (zero indexed, i.e. first outlet is index 0), in degrees
speaker_radians	id (int) azimuth (float) elevation (float)	set speaker azimuth/elevation for a given outlet (zero indexed, i.e. first outlet is index 0), in radians
max-rE		use max-rE weighting scheme
in-phase		use in-phase weighting scheme
none		use default weighting scheme
dump		print information about the encoder to the Max window

cosm.field

2D/3D interpolated field reading/writing using Jitter matrices. Briefly: a 2D or 3D matrix (the field) is input to the 3rd inlet, and a 2-plane or 3-plane (respectively) matrix of positions is input to the 1st inlet; the 1st outlet will return the interpolated field values for these positions.

The first inlet specifies a set of spatial locations (such as particles or agents); for 2D fields it should be 2-plane, for 3D fields, 3-plane; it should be float32 type. Each cell represents a 2D or 3D spatial location, in the range 0..1 (larger/smaller values will be wrapped).

The third inlet specifies the field (jitter matrix) to be indexed. It can 2D or 3D, and should be float32 type. Any number of planes are supported. Cosm.field will not work properly until a matrix has been send to the third inlet.

The first outlet returns interpolated field values for given positions. The output matrix therefore will have the same dimensions as the first inlet, but the same planes as the 3rd inlet.

With the attribute @writing 1, cosm.field can also modify the field matrix. Input a matrix to the 2nd inlet of values to add to the field: same dimensions as particles (1st inlet), up to as many planes as the field (3rd inlet). The accumulated additions of all particles are output to the 2nd outlet, which will match the dimensions and plane count of the field itself. For example:

Attributes

attribute	arguments	meaning
writing	0/1	if 1, a matrix sent to the second inlet specifies a set of values to add to the field. The dimensions should match those of the first inlet (the particles), and the planes should match those of the third inlet (the field). Modification will be accumulated and the output difference matrix is sent to the second outlet.

cosm.field.query

Indexes (or modifies) a field (2D/3D n-plane matrix), but by using individual messages rather than matrices to specify indices/additions. It is convenient to connect a cosm.nav directly up to a cosm.field.query to automatically report field values at the nav's current location.

Outlet: outputs the interpolated field values at the current position, one per plane of the field.

Messages

message	arguments	meaning
add	float array	one float per plane of the field. the float values are added to the field matrix in-place, distributed by interpolation over neighboring cells.
sub	float array	same as the add message, but subtracts rather than adds.
bang		report current interpolated field values at the last input position. outputs from the first outlet, a list of lfoats (one per plane of the field)

Attributes

attribute	arguments	meaning
position	x y z	position to index the field. positions are in world coordinates (minima and maxima specified by cosm.world), which will be mapped to the dimensions of the matrix.
field	symbol	name of a 2D/3D n-plane matrix to index

cosm.diffuse

2D/3D diffusion (by Gauss-Seidel relaxation) using Jitter matrices. An input matrix is diffused, and the resulting matrix is output.

Input matrix: n-plane, float32, 2D or 3D

Output matrix: matches input

Attributes

attribute	arguments	meaning
diffuse	float array	diffusion rate (0..1) for each plane (default 0.001)
accuracy	int	how accurate the diffusion model is (iterations of the Gauss-Seidel relaxation); defaults to 16.

cosm.gl.bounds

A Jitter Ob3D object. Draws a bounding box around the world dimensions. All standard Ob3D attributes and messages are supported (e.g. blend_enable, depth_enable, etc.)

First argument should be the draw context (the window name).

quat

Stores a quaternion (as a list of four floats); also supports quaternion multiplication (rotation). note: order of operations on quaternions is not commutative, that is, Q1 * Q2 != Q2 * Q1.

ARGUMents

arguments	meaning
int	how often quaternions are normalized. Reduce to improve object efficiency, but increase to avoid floating point error creeping into the angles. Defaults to every 30 operations.

Messages

message	arguments	meaning
list	float array (w x y z)	set and output the stored quaternion (first outlet)
set	float array (w x y z)	set but do not output the stored quaternion
bang		output the current stored quaternion (first outlet)
mul	float array (w x y z)	multiply the stored quaternion by the input quaternion (equivalent to rotation by the input quaternion).
rotate	float array (x y z)	rotates a vector by the stored quaternion; outputs to first outlet
reset		reset stored quaternion to default value (1 0 0 0)

quat2axis

Converts a quaternion into axis/angle format (as used by jit.gl.* rotate messages).

Messages

message	arguments	meaning
list	float array (w x y z)	sets the input quaternion, converts to axis/angle and outputs (first outlet)
bang		output the current stored quaternion as axis/angle(first outlet)

quat2euler

Converts a quaternion into euler format (azimuth/elevation/bank). NOTE: there is an inherent loss of information in the conversion from quaternion to Euler angles, and it is often not reversible. Euler angles are more intuitive than quaternions, but they suffer the gimbal lock problem.

Messages

message	arguments	meaning
list	float array (w x y z)	sets the input quaternion, converts to euler and outputs (first outlet)
bang		output the current stored quaternion as euler (first outlet)

quat2car

Retrieves a unit axis vector from the input quaternion. This can be very useful to retrieve forward, up and side vectors from a mobile object such as a cosm.nav, and likewise for placing objects in viewer-related positions (getting the quaternion from the camera by cosm.query).

ARGUMents

arguments	meaning
x or y or z or -x or -y or -z	which axis to retrieve from the quaternion.

Messages

message	arguments	meaning
list	float array (w x y z)	set the stored quaternion, and return the specified unit axis vector (first outlet)
bang		output the specified unit axis vector of the stored quaternion (first outlet)

axis2quat

Converts an axis/angle representation (as used in jit.gl.* rotate attributes) to quatnerion.

Messages

message	arguments	meaning
list	float array (angle x y z)	convert the input axis/angle to quatnerion, sets and output the stored quaternion (first outlet)
bang		output the current stored quaternion (first outlet)

euler2quat

Converts Euler angles (azimuth/elevation/bank, or yaw/pitch/roll, or heading/attitude/tilt) into quaternion. NOTE: there is an inherent loss of information in the conversion from quaternion to Euler angles, and it is often not reversible. Euler angles are more intuitive than quaternions, but they suffer the gimbal lock problem.

Messages

message	arguments	meaning
list	float array (az el ba)	sets the input Eeuler angles, converts to quaternion and outputs (first outlet)
bang		output the current stored quaternion (first outlet)

quatinverse

Inverts the input quaternion.

Messages

message	arguments	meaning
list	float array (w x y z)	quaternion to invert; result output from the first outlet
bang		output the current stored quaternion (first outlet)

quatpov

Rotates a cartesian point by a quaternion.

Messages

message	arguments	meaning
list	float array (x y z)	the cartesian point to rotate. executes the rotation and outputs the result position (first outlet)
quat	float array (w x y z)	the quaternion to rotate with. executes the rotation and outputs the result position (first outlet)
bang		output the current stored result position (first outlet)
dump		prints the stored matrix to the Max window

quatface

Stores a quaternion, a cartesian position, and an interpolation amount. Given a second cartesian point, it will produce a quaternion orientation that has rotated by amount along a curve between the original quaternion, and one which is facing the input point. It can be used to gradually rotate an object to follow another object.

ARGUMents

arguments	meaning
float	set interpolation amount

Messages

message	arguments	meaning
list	float array ( x y z)	set the cartesian point to turn to face; causes calculation and output of quaternion (first outlet)
quat	float array (w x y z)	set the stored quaternion of the object to turn
position	float array (x y z)	set the cartesian location of the object to turn
amount	float	set the interpolation amount (0..1)
bang		caclulate the output quaternion given the stored quaternion, position, target point and amount