Classes (extension) | Math

# SphericalDesign : ObjectExtension

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

## 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

### SphericalDesign.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.

### SphericalDesign.newT(numPoints, t)

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

### .rotate(angle)

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

### .tilt(angle)

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

### .tumble(angle)

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

### .mirrorX(recalcTriplets: true)

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

#### Arguments:

 recalcTriplets See explanation in -mirrorO.

### .mirrorY(recalcTriplets: true)

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

#### Arguments:

 recalcTriplets See explanation in -mirrorO.

### .mirrorZ(recalcTriplets: true)

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

#### Arguments:

 recalcTriplets See explanation in -mirrorO.

### .mirrorO(recalcTriplets: true)

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(methodOrFunc... args)

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.

### .nearestPoint(theta: 0, phi: 0)

Return the point nearest to [`theta, phi`].

### .nearestIndex(theta: 0, phi: 0)

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

### .pointsWithin(theta: 0, phi: 0, spread: 1.5707963267949, inclusive: true)

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(theta: 0, phi: 0, spread: 1.5707963267949, inclusive: true)

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(theta: 0, phi: 0, spread: 1.5707963267949, inclusive: true)

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

### .nearestIndicesWithin(theta: 0, phi: 0, spread: 1.5707963267949, inclusive: true)

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

### .vectorAngles(theta: 0, phi: 0)

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

### .points = cartesianArray

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 = azElArray

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.

### .visualize(parent, bounds, showConnections: true)

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(minSideLength: 0.01)

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.

## 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