SphericalDesign | SuperCollider 3.13.0 Help

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.¹

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

.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. ²

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

/*
Visualize the t-design to observe the effect of the methods.
showConnections = true will calculate the triangular mesh
(triplets) to visualize the convex hull.
*/

t = TDesign(13).visualize(showConnections: true);

/*
Perform rotations on the design.
Notice the design changes, not the view (the axes stay in place).
*/

t.rotate(-45.degrad);
t.tilt(45.degrad);
// ...etc.

/*
Mirror all points through the origin.
This invalidates the triplets, so recalcTriplets
is required to re-compute them.
*/

t.mirrorO(recalcTriplets: true);

/*
Perform arbitrary actions on the points in the design:
*/

// with a method Symbol
t.performOnDesign(\rotate, 30.degrad)

// or a Function
(
t.performOnDesign({ |cartesian, idx ... args|
    args.postln;
    // be sure to return a cartesian arg
    cartesian.y = cartesian.y.linlin(-1,1, -0.2, 1);
}, 1, 2, 3, 4)
)
// Note the above transform invalidates the spherical design as such!

// Reset to the original state.
t.reset;

/*
Directions returns an array with
[azimuth, elevation] for every point.
*/
t.directions;

// The indices of the triplets forming the triangular mesh.
t.triplets;
// >> nil, t was reset above.
// ...so we need to recalculate them:
/*
Caution: designs with large numbers of
points (over 50 or so) can take a long
time to calculate the triplets!
The view will automatically show the triplets.
*/
t.calcTriplets;

/*
Or you can explicitly tell the view to display the
connections between triplets.
*/

t.view.connectTriplets_(t.triplets);

/* Filter and select. */

// point nearest to direction
t.nearestPoint(pi/3, 0);
// index of the point nearest to direction
t.nearestIndex(pi/3, 0);

// points within a spherical cap
t.pointsWithin(0, pi/2, 2pi/3);

// points within a spherical cap, sorted nearest to farthest
t.nearestPointsWithin(0, pi/2, 2pi/3);

// indices of points within a spherical cap
t.indicesWithin(0, pi/2, 2pi/3);

// visualize them
t.view.highlightPoints(t.indicesWithin(0, pi/2, 2pi/3), Color.yellow)

// vector angles between each point and a direction
t.vectorAngles(25.degrad, -40.degrad);

t.view.close;

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

helpfile source: HelpSource/Classes/SphericalDesign.schelp
link::SphericalDesign/Classes/SphericalDesign::

SphericalDesignExtension

.new

.newT

Arguments:

.rotate

.tilt

.tumble

.mirrorX

Arguments:

.mirrorY

Arguments:

.mirrorZ

Arguments:

.mirrorO

Arguments:

.performOnDesign

Discussion:

.reset

.nearestPoint

.nearestIndex

.pointsWithin

.indicesWithin

.nearestPointsWithin

.nearestIndicesWithin

.vectorAngles

.points

Arguments:

.directions

Arguments:

.numPoints

.size

.triplets

.view

.visualize

Arguments:

.calcTriplets

.resetTriplets

.captureState

SphericalDesign
Extension