PointView:
Filter:
PointView/Classes (extension) | GUI

PointView
ExtensionExtension

An interactive view displaying a collection of points in 3D space.

PointView displaying a 15-point t-design

Description

An interactive view displaying a collection of points in 3D space. Points are Cartesian points (optionally specified as directional pairs of [azimuth, elevation]) rendered with adjustable 3D perspective or orthogonal projection. Points can be displayed with colors (-colorGroups) or connecting lines (-connections) to illustrate relationships between them.

The view and rotation controls are most conveniently changed through the UI built into the view, though these methods and more are available for more elaborate display of the points.

Class Methods

.new

Create a new PointView.

Arguments:

parent

An optional parent View in which to embed the PointView.

bounds

An optional Rect describing the bounds of the view.

Instance Methods

.points

Set the Array of Cartesian points to display. If resetConnections is false, any previously set -connections will remain, otherwise the default connections will be set to sequential indices [[0, 1, ... numPoints-1]].

.directions

Set the directions of points to display. dirArray can be an Array of:

If resetConnections is false, any previously set -connections will remain, otherwise the default connections will be set to sequential indices [[0, 1, ... numPoints-1]]. Directions are converted to Cartesian points internally.

.connections

Set/get the list of indices which are connected by lines.

NOTE: If you've set this value by keyword, getting this value will return the actual Array of connected indices, with the exception of \origin which returns this keyword (because the origin is technically not a point and therefore doens't have an index).

Arguments:

indicesOrKey

Set an Array of Arrays, each listing the indices of points which should be connected by lines.

Three keywords are also accepted:

\originconnect all points to the origin
\sequentialconnect all points in the order they were set
\triangulationconnect all points with a triangular mesh

If update is true, the connecting lines will immediately be shown.

close

A Boolean whether the end and start point of connection groups should be connected. This argument will set the instance state -closeConnections and will default to this state if the argument is nil.

Connections can be toggled on and off with -showConnections. Default connections are \sequential.

update

A Boolean whether to update the view with the new connections or not.

.closeConnections

Set a Boolean whether the end and start point of connection groups should be connected.

.triangulatePoints

Return an Array of triplets which are the indices of points forming the triangulation mesh across the points, similar to a convex hull. The results can be passed to -connectTriplets to display the triangulations. Returns nil if the triangulations can't be calculated.

.connectTriplets

Set an Array of Arrays, each listing the indices of points in groups of three that form a triangulation mesh across the points. This method is more efficient than setting connections to be the triplets directly, because it avoids repeated connections.

NOTE: For convenience, if you're connecting all points via triangulation, use this.connections_('triangulation') instead.

.numPoints

Get the number of points displayed.

View options

.pointColors

arrayOfColors can be a single Color, Array of Colors. If (arrayOfColors.size != numPoints), points will wrap through the color array.

.pointHueRange

Set the points to colors within a hue range. hueLow and hueHighare 0 <= hue < 1. Optionally specify saturation, value, and alpha, which are bound as in Color: *hsv. If scramble is true, the colors will be randomly distributed among the points instead of hues ascending with index.

.groupColors

arrayOfColors can be a single Color, Array of Colors. If (colorGroups.size != groupColors.size), groups will wrap through the color array. Indices not listed in the -colorGroups will be assigned the defaultColor.

.colorGroups

An Array of Arrays containing point indices to be set to each of the -groupColors. If (colorGroups.size != groupColors.size), groups will wrap through the -groupColors array. Indices not listed in the -colorGroups will be assigned the defaultColor.

.showConnections

A Boolean toggling the connection lines on and off. -connections must be set.

.connectionColor

Set/Get the color(s) of the lines showing the -connections. This can be a Color or an Array of Colors, one for each connection (i.e. the array size should equal connections.size, if smaller the connection colors will wrap through the provided array).

.connectionStrokeWidth

Get/set the stroke width of connection lines in pixels. The size determins the stroke width of the line nearest to the viewer, the farthest connection line widths will be scaled by -pointDistScale. This can be a Number or an Array of Numbers, one for each connection (i.e. the array size should equal connections.size, if smaller the connection stroke widths will wrap through the provided array).

.showAxes

A Boolean flag stating whether the display the axes at the origin. The length of the axes can be set with -axisScale.

.axisStrokeWidth

Set the stroke width of the axes at the origin, in pixels.

.axisColors

A 3-element Array of Colors in the order [x,y,z].

.axisScale

Adjust the length of the axes. scale of 1 makes the axes as long as the distance to the outermost point. Show/hide the axes with -showAxes.

.showIndices

A Boolean flag indicating whether to display the point indices or not.

.indicesColor

Set the Color of the text of the points' indices.

.pointSize

The diameter of the points, in pixels. If -renderDistanceSize is true, the nearest point will be the specified size;

.pointSizeScales

Arguments:

normArray

Scale each point by values in normArray. -clipExtend is used to ensure normArray.size == this.numPoints. Setting normArray to nil resets the points to the default uniform size.

.highlightPoints

Provide emphasis on specific points in the view through color.

Arguments:

arrayOfIndices

An Array of indices of the points to render in highlightColor.

highlightColor

The Color for highlighted points. Default Color.red.

defaultColor

The Color for non-highlighted points. Default Color.gray.alpha_(0.25).

.removeHighlight

Restore the points' colors to the state before they were set to -highlightPoints.

.units

Set the units, 'radians' or 'degrees', used by the GUI.

Movement: rotation

.rotate

.tilt

.tumble

The rotation of the displayed points, on each axis, in radians. Default positive directions are:

.rotateDir

.tiltDir

.tumbleDir

.allDir

A flag to specify the direction of rotation on each or all axes. A dir of 1 will select the default direction for that axis (see above) while -1 will invert the direction of rotation.

.reset

Reset rotations to defaults. (rotate = -45.degrad, tilt = 0, tumble = 0)

.rotateMode

Set the order of rotations when applying compound rotations to the points. 'rtt' for Rotate-Tilt-Tumble, 'ypr' Yaw-Pitch-Roll.

Movement: animation

.rotateOsc

.tiltOsc

.tumbleOsc

.allOsc

A Boolean flag stating whether the display (including axes) will oscillate around each axis or all axes.

.rotateOscPeriod

.tiltOscPeriod

.tumbleOscPeriod

.allOscPeriod

The period of oscillation on each axis or all axes, in seconds.

.rotateOscWidth

.tiltOscWidth

.tumbleOscWidth

.allOscWidth

Set the oscillation width of each axis or all axes, in radians.

.rotateCyc

.tiltCyc

.tumbleCyc

.allCyc

A Boolean flag stating whether the display (including axes) will rotate cyclically around each axis or all axes.

.rotateCycPeriod

.tiltCycPeriod

.tumbleCycPeriod

.allCycPeriod

The cycle period of each axis or all axes, in seconds.

.rotateCycRate

.tiltCycRate

.tumbleCycRate

.allCycRate

The cycle period of each axis or all axes, in Hertz.

.varyMotion

Set an axis ('rotate', 'tilt', or 'tumble') with a Boolean flag to randomize its motion, if it's oscillating or cycling.

.randomVariance

Set the random variance applied to those axes for which -varyMotion is true. The value of variance is normalized to the phase increment of each frame, so a variance of 0 has no effect, while a variance of 1 could potentially step twice as far (twice as fast) on each frame. Default is 0.15.

.frameRate

Set the framerate of the animation if the view is set to cycle (-rotateCyc) or oscillate (-rotateOsc).

Perspective

.setOrtho

Set the view to a flat orthographic projection along axis. This is useful for displaying symmetry of points through a plane.

Arguments:

axis

Avaible args: '+X', '-X', '+Y', '-Y', '+Z', '-Z'. The sign indicates the direction you're looking.

offset

Optionally offset the plane of projection by a radian amount. For example, some spherical designs will have interesting symmetry along a 45.degrad plane.

.setPerspective

Set the view to render the points in perspective (as opposed to an orthogonal view).

.translateX

Translate the origin of the display on the X axis. A norm of -1 and 1, is far left and right of the view, respectively.

.translateY

Translate the origin of the display on the Y axis. A norm of -1 and 1, is bottom and top of the view, respectively.

.skewX

Skew the perspective along the screen's X axis. A useful range of norm is 0 to 1.

.skewY

Skew the perspective along the screen's Y axis. A useful range of norm is 0 to 1.

.originDist

Move the origin of your points closer or farther from the screen. A useful range for norm values is about -0.5 (close) to 3 (far), but it depends also on the -eyeDist.

.eyeDist

A value which makes the the depth of the perspective more or less pronounced, qualitatively similar to moving your eye or a lens nearer or farther from your points. Useful norm values in a range of 1.5 (more warped) to 6 (less) are reasonable, but it depends also on the -originDist.

.renderDistanceSize

A Boolean to determine if point size changes with distance to enhance 3D effect.

.pointDistScale

Scale the size of the points with distance. A norm of 0.5 would scale the farthest point to be one half the size of the nearest point.

.refresh

Refresh the view. Most methods which change render settings refresh the view automatically.

Internal properties

.userView

Returns the UserView which is used for drawing the point display.

.pointsNorm

Return the Array of Cartesian points used internally for plotting. i.e. normalized to a radius of 1.

.pointsPx

Return the Array as Points, in pixels, relative to the center of the view. I.e. left of center will be a negative X value and above center will be a negative Y value.

Other

.export

Export the view to an image file.

Arguments:

fileName

A String that is the name of the file, including the extension. The extension isn't necessary, but you'll then need to specify the format and the file will be written without an extension.

directory

A String that is the directory into which the file will be written. Default is the user home directory, Platform.userHomeDir.

format

An optional String of the format to use. Image.formats lists supported formats. If nil, the format will be inferred from the path extension (the default).

quality

The quality factor in the range 0, small compressed files, to 100, large uncompressed files, or -1, the default settings. Default is -1.

hideControls

A Boolean specifying whether the controls should be hidden when exporting the image, so only the visualization is written to file.

finishCond

An optional Condition which will be set true and signal when the image has been written.

Examples