API Docs

Class: SphereGenerator

PD.BRep. SphereGenerator

A helper class for generating a range of spherical shapes as BReps.

This class generates spherical shapes using various methods for both the distribution of points over spherical angles and the tesselation of those points into surfaces. It includes a range of settings for adding random positional variation and 3D perlin noise to perturb the surface to create more organic and/or natural shapes.

This class is primarily used to generate tree canopies and rock elements, as well as geodesic and Fibonacci domes roofs.

new SphereGenerator( [config])

Creates a new randomisable sphere generation factory.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
jitter number <optional>

An amount of random positional variation, default to 0.
noiseFactor number <optional>

The magnitude of the Perlin noise function, defaults to 0.
noiseScale number <optional>

The scale of the Perlin noise function(0 to 10), defaults to 1.
noiseOffset number <optional>

The offset of the Perlin noise function, default to 0.
center THREE.Vector3 <optional>

The center of the shape in model space, defaults to the origin.
size THREE.Vector3 <optional>

The size of the shape in each axis, defaults to 1000mm.
Author:
  • drajmarsh

Members

:THREE.Box3

boundingBox

The spatial extents of points added since last reset.

Type
  • THREE.Box3
:THREE.Vector3

center

The center point to use for the shape, defaults to the origin.

Type
  • THREE.Vector3
:number

jitter

An amount of random positional variation, default to zero.

Type
  • number
:number

minZ

The minimum allowable Z-axis value, defaults to -Infinity.

Type
  • number
:number

noiseFactor

The magnitude of the Perlin noise function, defaults to zero.

Type
  • number
:number

noiseOffset

The offset of the Perlin noise function, default to 0.

Type
  • number
:number

noiseScale

The scale of the Perlin noise function(0 to 10), defaults to 1.

Type
  • number
:THREE.Vector3

pos

Stores the last computed 3D position.

Type
  • THREE.Vector3
:number

rotation

An offset rotation of polar azimuth angles.

Type
  • number
:THREE.Vector3

size

The size of the shape in each axis, defaults to 1000mm.

Type
  • THREE.Vector3
:number

umbrellaEffect

If points fall below minZ, are they flattened or reflected up to form an umbrella shape.

This value is a fractional multiplier of the sphere radius. When zero, points below the minimum will be flattened at minZ. When greater than zero, points will be projected upwards by this amount.

Type
  • number
:THREE.Vector3

vector

A vector used to convert spherical/cartesian coordinates.

Type
  • THREE.Vector3

Methods

applyJitter(pos)

Applies the current jitter value to the given point in each axis.

This method updates boundingBox to accommodate the new calculated position.

Parameters:
Name Type Description
pos THREE.Vector3

The 3D model position to modify.
Returns:

Returns the pos argument to support method chaining.

Type
THREE.Vector3

applyJitterToArray(coord)

Applies the current jitter value to the given coordinate in each axis.

This method DOES NOT update boundingBox.

Parameters:
Name Type Description
coord Array

The [x,y,z] coordinate array to modify.
Returns:

Returns the coordinate array.

Type
Array

applyNoiseFromCenter(pos)

Applies bumpiness to the point relative to center.

The calculated point is centered at the current center position and the radius in each axis is given by the current size vector.

This method updates boundingBox to accommodate the new calculated position.

Parameters:
Name Type Description
pos THREE.Vector3

The 3D model position to modify.
Returns:

Returns the pos argument to support method chaining.

Type
THREE.Vector3

applyRandomnessToArray(coord, factor)

Applies the given randomisation factor to the given coordinate in each axis.

This method DOES NOT update boundingBox.

Parameters:
Name Type Description
coord Array

The [x,y,z] coordinate array to modify.
factor number

The randomisation amount to apply.
Returns:

Returns the coordinate array.

Type
Array

applyRandomnessToPoint(pos, factor)

Applies the given randomisation factor to the given point in each axis.

This method updates boundingBox to accommodate the new calculated position.

Parameters:
Name Type Description
pos THREE.Vector3

The 3D model position to modify.
factor number

The randomisation amount to apply.
Returns:

Returns the pos argument to support method chaining.

Type
THREE.Vector3

expandBBoxByVecArray(coord)

Expand the bounding box by the given coordinate array.

Parameters:
Name Type Description
coord Array

The [x,y,z] coordinate array to fit.

generateFacesConvexHull(points3d)

Uses QuickHull to triangulate points into faces.

Parameters:
Name Type Description
points3d Array

An array of corresponding 3d points in model space.
Returns:

Returns an array of triangles with three coordinate arrays per entry.

Type
Array

generateFacesDelaunay(points2d, points3d)

Uses Delaunay triangulation to generate BRep from spherical points.

Parameters:
Name Type Description
points2d Array

An array of [azi,alt] 2d stereographic points.
points3d Array

An array of corresponding 3d points in model space.
Returns:

Returns an array of triangle contours with three coordinate arrays per entry.

Type
Array

generateFacesVoronoi(points2d)

Uses Voronoi cellularisation to generate canopy BRep from points.

Parameters:
Name Type Description
points2d Array

An array of [azi,alt] 2d stereographic points.
Returns:

Returns an array of polygonal contours of sequential coordinate arrays.

Type
Array

getPerlinNoise(pos)

Computes a spatial Perlin noise value for the given point.

Parameters:
Name Type Description
pos THREE.Vector3

The 3D model position to compute a value for.
Returns:

Returns the results of the noise function.

Type
number

initialise(jitter, factor, scale, offset [, minZ] [, umbrella] [, rotation])

Set the jitter and Perlin noise values for subsequent shapes.

This method also empties the PD.BRep.SphereGenerator#boundingBox property and sets minZ back to -Infinity.

Parameters:
Name Type Argument Description
jitter number

The magnitude of random positional displacement, in model units.
factor number

The magnitude of noise-driven surface displacement, in model units.
scale number

The scale the noise function, typically a fraction (0 to 1).
offset number

The offset into the noise function, given as a fraction (0 to 1).
minZ number <optional>

An optional minimum Z value to restrict the shape to.
umbrella number <optional>

An optional Z reflection modifier for points below minZ.
rotation number <optional>

An optional polar azimuth rotation angle.
Returns:

Returns this sphere factory to support method chaining.

Type
PD.BRep.SphereGenerator

pointDistributionFibonacci(num_pts, points2d, points3d [, dome])

Generates a set of regularly distributed 3D points over the surface of a sphere.

The distribution of points is based in the Fibonacci spiral which gives a pretty good approximation of equally-spaced points.

If a valid points2d array is given, this method fills it with the 2D stereographic position of each point. If a valid points2d array is given, it is filled with the corresponding 3D spatial position of each point.

Parameters:
Name Type Argument Default Description
num_pts number

The number of random points to generate.
points2d Array | null

An array to store 2D stereographic points, use null to ignore.
points3d Array | null

An array to store 3D spherical points, use null to ignore.
dome boolean <optional>
 false

A flag for restricting points to only the top hemisphere, defaults to false.

pointDistributionGeodesic(detail, points2d, points3d [, dome])

Generates a set of geodesically distributed 3D points over the surface of a sphere.

This distribution is generated by progressively dividing into spherical triangles and then inflating the interpolated points to the radius of the sphere.

If a valid points2d array is given, this method fills it with the 2D stereographic position of each point. If a valid points2d array is given, it is filled with the corresponding 3D spatial position of each point.

Parameters:
Name Type Argument Default Description
detail number

The level of triangulation detail (0 to 16).
points2d Array | null

An optional array to store 2D stereographic points.
points3d Array | null

An optional array to store 3D spherical points.
dome boolean <optional>
 false

A flag for restricting points to only the top hemisphere, defaults to false.

pointDistributionPseudoRandom(azi_bands, alt_bands, points2d, points3d)

Generates a set of random 3D points in bands over the surface of a sphere.

If a valid points2d array is given, this method fills it with the 2D stereographic position of each point. If a valid points2d array is given, it is filled with the corresponding 3D spatial position of each point.

NOTE: This method applies an arbitrary range for both bands of between 3 and 128.

Parameters:
Name Type Description
azi_bands number

The number of azimuth bands (3 to 128).
alt_bands number

The number of altitude bands (3 to 128).
points2d Array | null

An optional array to store 2D stereographic points.
points3d Array | null

An optional array to store 3D spherical points.

pointDistributionRandom(num_pts, points2d, points3d)

Generates a set of completely random 3D coordinates over the surface of a sphere.

The sphere is centered at the current center position and the radius in each axis is given by the current size vector. In addition to the number of points specified, 6 core points are added to form a random tetrahedron to give the sphere some basic shape.

If a valid points2d array is given, this method fills it with the 2D stereographic position of each point. If a valid points2d array is given, it is filled with the corresponding 3D spatial position of each coordinate.

The resulting array(s) of 2D and/or 3D coordinates can then be used by the Delaunay, Voronoi or QuickHull surface generation methods.

Parameters:
Name Type Description
num_pts number

The number of random points to generate.
points2d Array | null

An optional array to store 2D stereographic points.
points3d Array | null

An optional array to store 3D spherical points.

polarToSphere(azi, alt [, no_jitter])

Converts spherical coordinates to cartesian relative to the given origin.

The resulting position is based on the current centre point location and size of the shape. If the noiseFactor property is greater than zero, it will also be perturbed by the noise function.

This method sets the vector property to the normalised direction of the point from the center, and sets the pos property to the resulting 3D position. It also updates boundingBox to accommodate the calculated position.

Parameters:
Name Type Argument Description
azi number

The horizontal azimuth angle, in radians anti-clockwise from +X axis.
alt number

The vertical angle, in radians above the horizontal plane.
no_jitter boolean <optional>

When true, no jitter is applied to the shared point.
Returns:

Returns the shared pos point object.

Type
THREE.Vector3

polarToStereo(azi, alt)

Converts spherical coordinates to 2D stereographic.

Parameters:
Name Type Description
azi number

The horizontal azimuth angle, in radians anti-clockwise from +X axis.
alt number

The vertical angle, in radians above the horizontal plane.
Returns:

Returns an [x,y] coordinate array.

Type
Array

stereoToSphere(p2d, radius_xy, radius_z)

Converts 2D coordinates to cartesian with noise relative to the center.

The calculated point is centered at the current center position and the radius in each axis is given by the current size vector.

This method updates boundingBox to accommodate the new calculated position.

Parameters:
Name Type Description
p2d Array

A [azi,alt] polar position array.
radius_xy number

The radius from the center point in the X and Y axis.
radius_z number

The radius from the center point in the Z axis.
Returns:

Returns an [x,y,z] coordinate array.

Type
Array