SphericalDesign:
Filter:
SphericalDesign/Classes (extension) | Math

SphericalDesign
ExtensionExtension

A class encapsulating a set of points which represent a spherical design, allowing for searching, basic transformations and visualization of the design.

Description

Spherical designs
Let X be a finite subset of S^(n−1). Spherical codes and spherical designs are nothing but finite subsets of S^(n−1). Roughly speaking, the code theoretical viewpoint is to try to find X, whose points are scattered on S^(n−1) as far as possible, i.e. the minimum distance of X is as large as possible for a given size of X. ... On the other hand, the design theoretical viewpoint is to try to find X which globally approximates the sphere S^(n−1) very well.1

This class does not strictly enforce the definition of a spherical design, in fact it is just a collection of points (Cartesian objects) which you can set arbitrarily. The expectation however is that you'll be importing designs that are provided, such as those t-designs available through the subclass TDesign, or assigning your own points to be regarded as a spherical design.

NOTE: The coordinate system follows that of Spherical and Polar. The +X axis points forward, +Y points left, +Z points upward.

Class Methods

.new

Create an empty SphericalDesign without any initial points. To populate a design with predefined design points, use one of the subclasses, or the convenience methods provided in this class such as *newT for a spherical t-design.

.newT

Returns a new TDesign.

Arguments:

numPoints

The number of points you'd like in your design. If multiple matches in the design library are found, the t argument must be specified to disambiguate, otherwise an error will be thrown.

t

The desired t parameter. Can be nil but the method will throw an error if multiple design matches are found for numPoints. (Some valid designs include the same number of points but different values of t.)

Instance Methods

Transforming

.rotate

Rotate all points in the design around the origin. Positive rotation is counter clockwise.

.tilt

Tilt all points in the design around the origin. Positive tilt moves the leftmost point (+Y) toward the zenith (+Z).

.tumble

Tumble all points in the design around the origin. Positive tumble moves the forward point (+X) toward the zenith (+Z).

.mirrorX

Reflect all points in the design along the X axis (through the YZ plane).

Arguments:

recalcTriplets

See explanation in -mirrorO.

.mirrorY

Reflect all points in the design along the Y axis (through the XZ plane).

Arguments:

recalcTriplets

See explanation in -mirrorO.

.mirrorZ

Reflect all points in the design along the Z axis (through the XY plane).

Arguments:

recalcTriplets

See explanation in -mirrorO.

.mirrorO

Reflect all points in the design through the origin.

Arguments:

recalcTriplets

Mirroring the design invalidates the design's -triplets. By default, if triplets have already been calculated, they will be recalculated, unless recalcTriplets is false. This can be useful if you're working with a design and want to perform multiple transformations before re-calculating the triplets (which can take some time for large designs).

.performOnDesign

If methodOrFunc is a Symbol, this method behaves as Object: -perform, iterating over each Cartesian point.

If methodOrFunc is a Function, this method evaluates the function for each point, passing in as arguments: the Cartesian point, the point index, and *args.

Discussion:

If the method you perform on the design invalidates the design's -triplets (assuming you've calculated and are using them), you'll want to either -resetTriplets beforehand to clear them and/or call -calcTriplets after performing the method.

.reset

Reset the points to their the positions when -captureState was called. TDesign, for example, captures the initial state of the points on creation.

Sorting and selecting

.nearestPoint

Return the point nearest to [theta, phi].

.nearestIndex

Return the index of point nearest to [theta, phi].

.pointsWithin

Returns an Array of the Cartesian points that lie within a region centered at [theta, phi] with an extent of spread radians across. Points exactly on the boundary will be included if inclusive is true.

.indicesWithin

Returns an Array of the Cartesian points that lie within a region centered at [theta, phi] with an extent of spread radians across. Points exactly on the boundary will be included if inclusive is true.

.nearestPointsWithin

Same as -pointsWithin, but the point indices are sorted by ascending distance from [theta, phi].

.nearestIndicesWithin

Same as -indicesWithin, but the point indices are sorted by ascending distance from [theta, phi].

.vectorAngles

Returns an Array of anglular distances from [theta, phi] to each point.

State variables

.points

Get/set the points that comprise the spherical design. In normal use you would not set this directly but rather this would be set by the underlying design library.

Arguments:

cartesianArray

An Array of Cartesian objects.

.directions

Get/set the directions (azimuth, elevation) of points that comprise the spherical design. The resulting -points are assigned a rho of 1, so they lie on the surface of a unit sphere. In normal use you would not set this directly but rather this would be set by the underlying design library.

Arguments:

azElArray

Directions are specified and returned as a 2D Array of [azimuth, elevation] (theta, phi) pairs.

.numPoints

Returns the number of points in the design. Synonymous with -size.

.size

Returns the number of points in the design. Synonymous with -numPoints.

.triplets

Returns an Array of triplets (an Array of three Floats) describing the indices of triangles formed through the calculation of the triangular mesh across the points.

Returns nil if triplets haven't yet been calculated. See -calcTriplets for more information.

.view

Return the PointView created after calling -visualize.

Other

.visualize

Create a PointView displaying the design.

Arguments:

parent

An optional View to hold the PointView.

bounds

An optional Rect describing the position and size of the PointView.

showConnections

A Boolean denoting whether connecting lines between points will be displayed on opening. The connections between points will default to the corresponding -triplets, so if showConnections is true (default), they will be calculated. This calculation can take a long time. See the WARNING in -calcTriplets.

.calcTriplets

Calculate the triangular mesh across the points and populate -triplets with indices of the triangles. Similar to the Delaunay triangulation or convex hull, which is useful for visualization (see -visualize) and generating triangles for VBAP. 2

WARNING: This calculation can take a long time for numPoints above 30 or so. 50 points: ~5 sec, 70 points: ~11 sec, 120 points: ~70 seconds, ...

.resetTriplets

Set -triplets to nil and clear the internal table of vector angles between points. If you're working with large designs and transforming, etc., this may be useful to manually reset these internal variables.

.captureState

Capture the state to which you'd like to return when calling -reset. TDesign, for example, captures the initial state of the points on creation.

Examples

Authors

M. McCrea, D. Peterson 2018

[1] - Bannai, E., Bannai, E. A survey on spherical designs and algebraic combinatorics on spheres. European Journal of Combinatorics, Volume 30, Issue 6, August 2009, Pages 1392-1425.
[2] - -calcTriplets and its associated methods were copied, with some modification, from Scott Wilson's port (VBAPSpeakerArray) of Ville Pukki's VBAP library in PureData. Full attribution and copyright can be found in the source file extSphericalDesign.sc