diff --git a/src/builders/Builder.ts b/src/builders/Builder.ts index e1e1248..19a1784 100644 --- a/src/builders/Builder.ts +++ b/src/builders/Builder.ts @@ -1,24 +1,80 @@ import Module from '@app/module/Module'; import NoiseMap from '@app/noisemap'; +/** + * Abstract base class for a noise-map builder + * + * A builder class builds a noise map by filling it with coherent-noise + * values generated from the surface of a three-dimensional mathematical + * object. Each builder class defines a specific three-dimensional + * surface, such as a cylinder, sphere, or plane. + * + * A builder class describes these input values using a coordinate system + * applicable for the mathematical object (e.g., a latitude/longitude + * coordinate system for the spherical noise-map builder.) It then + * "flattens" these coordinates onto a plane so that it can write the + * coherent-noise values into a two-dimensional noise map. + */ export default abstract class Builder { + /** + * The source module. + * + * This object fills in a noise map with the coherent-noise values + * from this source module. + * + * The source module must exist throughout the lifetime of this + * object unless another noise module replaces that noise module. + */ public sourceModule: Module; + /** + * The destination noise map. + * + * The destination noise map will contain the coherent-noise values + * from this noise map after a successful call to the Build() method. + * + * The destination noise map must exist throughout the lifetime of + * this object unless another noise map replaces that noise map. + */ public noiseMap: NoiseMap; + /** + * @param sourceModule The source module + * @param width The width of the destination noise map, in points + * @param height The height of the destination noise map, in points + */ public constructor(sourceModule: Module, width: number, height: number) { this.sourceModule = sourceModule; this.noiseMap = new NoiseMap(width, height); } // Functions + /** + * Builds the noise map. + * @returns Updated instance of noise map + */ public abstract build(): NoiseMap; + /** + * Sets the size of the destination noise map. + * + * @param width The width of the destination noise map, in points. + * @param height The height of the destination noise map, in points. + * + * This method does not change the size of the destination noise map + * until the Build() method is called. + */ public setSize(width: number, height: number): void { this.width = width; this.height = height; } // Properties + /** + * The width of the destination noise map, in points. + * + * This object does not change the width in the destination noise + * map object until the build() method is called. + */ public get width(): number { return this.noiseMap.width; } @@ -26,6 +82,12 @@ export default abstract class Builder { this.noiseMap.width = width; } + /** + * The height of the destination noise map, in points. + * + * This object does not change the height in the destination noise + * map object until the build() method is called. + */ public get height(): number { return this.noiseMap.height; } diff --git a/src/builders/cylinder.ts b/src/builders/cylinder.ts index 0156b3b..35c5d0b 100644 --- a/src/builders/cylinder.ts +++ b/src/builders/cylinder.ts @@ -2,12 +2,40 @@ import Cylinder from '@app/model/cylinder'; import NoiseMap from '@app/noisemap'; import Builder from './Builder'; +/** + * Builds a cylindrical noise map. + * + * This class builds a noise map by filling it with coherent-noise values + * generated from the surface of a cylinder. + * + * This class describes these input values using an (angle, height) + * coordinate system. After generating the coherent-noise value from the + * input value, it then "flattens" these coordinates onto a plane so that + * it can write the values into a two-dimensional noise map. + * + * The cylinder model has a radius of 1.0 unit and has infinite height. + * The cylinder is oriented along the y axis. Its center is at the + * origin. + * + * The x coordinate in the noise map represents the angle around the + * cylinder's y axis. The y coordinate in the noise map represents the + * height above the x-z plane. + * + * The application must provide the lower and upper angle bounds of the + * noise map, in degrees, and the lower and upper height bounds of the + * noise map, in units. + */ class NoiseMapBuilderCylinder extends Builder { private _lowerAngleBound: number = 0; private _lowerHeightBound: number = 0; private _upperAngleBound: number = 1; private _upperHeightBound: number = 1; + /** + * Lower angle boundary of the cylindrical noise map, in degrees. + * + * The lower angle boundary must be less than the upper angle boundary. + */ public get lowerAngleBound(): number { return this._lowerAngleBound; } @@ -19,6 +47,12 @@ class NoiseMapBuilderCylinder extends Builder { this._lowerAngleBound = v; } + /** + * Lower height boundary of the cylindrical noise map, in units. + * One unit is equal to the radius of the cylinder. + * + * The lower height boundary must be less than the upper height boundary. + */ public get lowerHeightBound(): number { return this._lowerHeightBound; } @@ -30,6 +64,11 @@ class NoiseMapBuilderCylinder extends Builder { this._lowerHeightBound = v; } + /** + * Upper angle boundary of the cylindrical noise map, in degrees. + * + * The upper angle boundary must be greater than the lower angle boundary. + */ public get upperAngleBound(): number { return this._upperAngleBound; } @@ -41,6 +80,12 @@ class NoiseMapBuilderCylinder extends Builder { this._upperAngleBound = v; } + /** + * Upper height boundary of the cylindrical noise map, in units. + * One unit is equal to the radius of the cylinder. + * + * The upper height boundary must be greater than the lower height boundary. + */ public get upperHeightBound(): number { return this._upperHeightBound; } @@ -75,10 +120,20 @@ class NoiseMapBuilderCylinder extends Builder { return this.noiseMap; } - public setBounds(lowerAngleBound: number, lowerHeightBound: number, upperAngleBound: number, upperHeightBound: number): void { + /** + * Sets the coordinate boundaries of the noise map. + * + * @param lowerAngleBound The lower angle boundary of the noise map, in degrees. + * @param upperAngleBound The upper angle boundary of the noise map, in degrees. + * @param lowerHeightBound The lower height boundary of the noise map, in units. + * @param upperHeightBound The upper height boundary of the noise map, in units. + * + * One unit is equal to the radius of the cylinder. + */ + public setBounds(lowerAngleBound: number, upperAngleBound: number, lowerHeightBound: number, upperHeightBound: number): void { this.lowerAngleBound = lowerAngleBound; - this.lowerHeightBound = lowerHeightBound; this.upperAngleBound = upperAngleBound; + this.lowerHeightBound = lowerHeightBound; this.upperHeightBound = upperHeightBound; } } diff --git a/src/builders/plane.ts b/src/builders/plane.ts index f314ea9..c59ea69 100644 --- a/src/builders/plane.ts +++ b/src/builders/plane.ts @@ -4,19 +4,52 @@ import Module from '@app/module/Module'; import NoiseMap from '@app/noisemap'; import Builder from './Builder'; +/** + * Builds a planar noise map. + * + * This class builds a noise map by filling it with coherent-noise values + * generated from the surface of a plane. + * + * This class describes these input values using (x, y) coordinates. + * Their z coordinates are always 0.0. + * + * The application must provide the lower and upper x coordinate bounds + * of the noise map, in units, and the lower and upper y coordinate + * bounds of the noise map, in units. + * + * To make a tileable noise map with no seams at the edges, set `seamless` to true. + */ +// @TODO refactor y coordinates into z coordinates class NoiseMapBuilderPlane extends Builder { - private seamless: boolean; + /** + * A flag that enables or disables seamless tiling. + * + * Enabling seamless tiling builds a noise map with no seams at the + * edges. This allows the noise map to be tileable. + */ + public seamless: boolean; private _lowerXBound: number = 0; private _lowerYBound: number = 0; private _upperXBound: number = 1; private _upperYBound: number = 1; + /** + * @param sourceModule The source module + * @param width The width of the destination noise map, in points + * @param height The height of the destination noise map, in points + * @param seamless A flag that enables or disables seamless tiling + */ constructor(sourceModule: Module, width: number = 256, height: number = 256, seamless: boolean = false) { super(sourceModule, width, height); this.seamless = seamless; } + /** + * The lower x boundary of the noise map, in units. + * + * The lower x boundary must be less than the upper x boundary. + */ public get lowerXBound(): number { return this._lowerXBound; } @@ -28,6 +61,11 @@ class NoiseMapBuilderPlane extends Builder { this._lowerXBound = v; } + /** + * The lower y boundary of the noise map, in units. + * + * The lower y boundary must be less than the upper y boundary. + */ public get lowerYBound(): number { return this._lowerYBound; } @@ -39,6 +77,11 @@ class NoiseMapBuilderPlane extends Builder { this._lowerYBound = v; } + /** + * The upper x boundary of the noise map, in units. + * + * The upper x boundary must be greater than the lower x boundary. + */ public get upperXBound(): number { return this._upperXBound; } @@ -50,6 +93,11 @@ class NoiseMapBuilderPlane extends Builder { this._upperXBound = v; } + /** + * The upper y boundary of the noise map, in units. + * + * The upper y boundary must be greater than the lower y boundary. + */ public get upperYBound(): number { return this._upperYBound; } @@ -115,6 +163,14 @@ class NoiseMapBuilderPlane extends Builder { return this.noiseMap; } + /** + * Sets the boundaries of the planar noise map. + * + * @param lowerXBound The lower x boundary of the noise map, in units. + * @param lowerYBound The lower y boundary of the noise map, in units. + * @param upperXBound The upper x boundary of the noise map, in units. + * @param upperYBound The upper y boundary of the noise map, in units. + */ public setBounds(lowerXBound: number, lowerYBound: number, upperXBound: number, upperYBound: number): void { this.upperXBound = upperXBound; this.upperYBound = upperYBound; diff --git a/src/builders/sphere.ts b/src/builders/sphere.ts index ea1e075..2f41737 100644 --- a/src/builders/sphere.ts +++ b/src/builders/sphere.ts @@ -3,12 +3,37 @@ import Module from '@app/module/Module'; import NoiseMap from '@app/noisemap'; import Builder from './Builder'; +/** + * Builds a spherical noise map. + * + * This class builds a noise map by filling it with coherent-noise values + * generated from the surface of a sphere. + * + * This class describes these input values using a (latitude, longitude) + * coordinate system. After generating the coherent-noise value from the + * input value, it then "flattens" these coordinates onto a plane so that + * it can write the values into a two-dimensional noise map. + * + * The sphere model has a radius of 1.0 unit. Its center is at the + * origin. + * + * The x coordinate in the noise map represents the longitude. The y + * coordinate in the noise map represents the latitude. + * + * The application must provide the southern, northern, western, and + * eastern bounds of the noise map, in degrees. + */ class NoiseMapBuilderSphere extends Builder { private _eastLonBound: number; private _northLatBound: number; private _southLatBound: number; private _westLonBound: number; + /** + * @param sourceModule The source module + * @param width The width of the destination noise map, in points + * @param height The height of the destination noise map, in points + */ constructor(sourceModule: Module, width: number = 256, height: number = 256) { super(sourceModule, width, height); @@ -18,17 +43,11 @@ class NoiseMapBuilderSphere extends Builder { this._westLonBound = 0.0; } - public get eastLonBound(): number { - return this._eastLonBound; - } - public set eastLonBound(v: number) { - if (v <= this.westLonBound) { - throw new Error('East longitudinal bound cannot be equal to or less than west longitudinal bound!'); - } - - this._eastLonBound = v; - } - + /** + * Northern boundary of the spherical noise map, in degrees. + * + * The northern latitudinal bound must be greater than the southern latitudinal bound. + */ public get northLatBound(): number { return this._northLatBound; } @@ -40,6 +59,11 @@ class NoiseMapBuilderSphere extends Builder { this._northLatBound = v; } + /** + * Southern boundary of the spherical noise map, in degrees. + * + * The southern latitudinal bound must be less than the northern latitudinal bound. + */ public get southLatBound(): number { return this._southLatBound; } @@ -51,6 +75,27 @@ class NoiseMapBuilderSphere extends Builder { this._southLatBound = v; } + /** + * Eastern boundary of the spherical noise map, in degrees. + * + * The eastern longitudinal bound must be greater than the western longitudinal bound. + */ + public get eastLonBound(): number { + return this._eastLonBound; + } + public set eastLonBound(v: number) { + if (v <= this.westLonBound) { + throw new Error('East longitudinal bound cannot be equal to or less than west longitudinal bound!'); + } + + this._eastLonBound = v; + } + + /** + * Western boundary of the spherical noise map, in degrees. + * + * The western longitudinal bound must be greater than the eastern longitudinal bound. + */ public get westLonBound(): number { return this._westLonBound; } @@ -87,11 +132,19 @@ class NoiseMapBuilderSphere extends Builder { } - public setBounds(westLonBound: number, eastLonBound: number, southLatBound: number, northLatBound: number): void { - this.westLonBound = westLonBound; - this.eastLonBound = eastLonBound; + /** + * Sets the coordinate boundaries of the noise map. + * + * @param southLatBound The southern boundary of the noise map, in degrees. + * @param northLatBound The northern boundary of the noise map, in degrees. + * @param westLonBound The western boundary of the noise map, in degrees. + * @param eastLonBound The eastern boundary of the noise map, in degrees. + */ + public setBounds(southLatBound: number, northLatBound: number, westLonBound: number, eastLonBound: number): void { this.southLatBound = southLatBound; this.northLatBound = northLatBound; + this.westLonBound = westLonBound; + this.eastLonBound = eastLonBound; } }