Analytics

THREE.Terrain includes a library, src/analytics.js, which provides statistics about a terrain. This library is not bundled into THREE.Terrain.js (or THREE.Terrain.min.js) so using it requires explicitly including it in your page. The demo also includes an "Analysis" panel showing statistics for the terrain being viewed. The screenshot below shows the "Analysis" panel on the left:

Running an analysis

You can analyze a terrain like this:

var analysis = THREE.Terrain.Analyze(mesh, properties);

In this call, mesh is the THREE.Mesh instance representing the terrain, and properties is an object holding properties of the terrain. You can (and usually should) pass the same object as properties that you pass as the options parameter to the THREE.Terrain() call when generating a terrain. At a minimum, properties must contain the maxHeight, minHeight, xSegments, ySegments, xSize, and ySize attributes.

The resulting analysis object contains the properties and methods detailed below.

Properties of analysis

The analysis object contains values corresponding to the following sections.

Elevation and Slope

The analysis.elevation object contains summary statistics relating to terrain elevation data. The analysis.slope object contains summary statistics relating to terrain slope data. They have the same properties, so they are covered together below.

"Slope" here refers to the angle (in degrees) between the horizontal plane and a face of the terrain mesh.

• Sample size (elevation.sampleSize, slope.sampleSize): The number of values in the data set. For elevation, this is the number of vertices in the terrain mesh ((properties.xSegments + 1) * (properties.ySegments + 1)). For slope, this is the number of faces in the terrain mesh (properties.xSegments * properties.ySegments * 2).
• Min (elevation.min, slope.min): The smallest value in the data set (that is, the elevation of the lowest vertex, or the flattest slope). For elevation, this is typically the same as properties.minHeight.
• Max (elevation.max, slope.max): The largest value in the data set (that is, the elevation of the highest vertex, or the steepest slope). For elevation, this is typically the same as properties.maxHeight.
• Range (elevation.range, slope.range): The difference between the max and the min.
• Midrange (elevation.midrange, slope.midrange): The value in the middle of max and min (i.e. their average) - that is, (max - min) / 2 + min.
• Median (elevation.median, slope.median): The value in the middle of the data set (half the data will be higher than this value, and half will be lower).
• Interquartile Range / IQR (elevation.iqr, slope.iqr): The difference between the 75th and 25th percentiles of the data. That is, 50% of the data is found within a range of this size.
• Mean (elevation.mean, slope.mean): The average (arithmetic mean) of the data.
• Standard deviation / Std dev / Dispersion (elevation.stdev, slope.stdev): A measure of how spread out the data is. Higher values mean the data is more spread out.
• Median Absolute Deviation / MAD (elevation.mad, slope.mad): Another measure of how spread out the data is. Higher values mean the data is more spread out.
• Mode (elevation.modes, slope.modes): The most frequently occurring value(s) in the data. This is calculated by dropping the fractional part of each datum, because normally most values in the data sets will be unique.
• Pearson skew (elevation.pearsonSkew, slope.pearsonSkew): A measure of data symmetry. That is, values farther from zero mean more of the data (e.g. more vertices or more slopes) occurs at one end of the range. Technically this is the "moment coefficient of skewness."
• Groeneveld & Meeden's coefficient / G&M skew (elevation.groeneveldMeedenSkew, slope.groeneveldMeedenSkew): Another measure of data symmetry. Values farther from zero mean more of the data occurs at one end of the range.
• Kurtosis (elevation.kurtosis, slope.kurtosis): Describes the shape ("peakedness") of the data. Higher values generally indicate that the data is more concentrated around its center, and lower values indicate that the data is more distributed. Technically this is the "excess kurtosis," meaning it describes how heavy the "tails" of the data distribution are relative to a normal distribution.

Methods

Both the analysis.elevation and the analysis.slope objects have the following methods:

• percentile(p): Calculates the value in the data set at the given percentile p. If there is not a value in the data set that is exactly at the given percentage, the returned value is based on a linear interpolation between the nearest values. Specifically, p% of the data will be less than the returned value.
• percentRank(v): Calculates the percentile of a given value v in the data set's range. That is, the returned value indicates what percent of the data is less than the given value.
• drawHistogram(canvas, bucketCount): Draws a histogram of the data onto canvas with bucketCount bars.

Roughness

The analysis.roughness object contains summary statistics relating to the roughness of the terrain.

• 2D to 3D area ratio (roughness.planimetricAreaRatio): The ratio of the 2D areas of the terrain mesh's faces to the 3D areas of those faces. The 3D area is larger (unless the face is flat) because of its slope. As a result, this is a measurement of how sloped the terrain is; lower values indicate steeper slopes.
• Terrain Ruggedness Index / TRI (roughness.terrainRuggednessIndex): A measure of the difference in elevation between points in the terrain and their neighboring points. Larger values indicate that there is greater deviation, meaning the terrain is more rugged (at any given point, the surroundings are steeper).
• Jaggedness (roughness.jaggedness): Measures what percent of vertices in the terrain mesh are either the highest or lowest in their neighborhoods (i.e. among the vertices immediately adjacent to them). The lower the value, the smoother the terrain is.

Fitted plane

The analysis.fittedPlane object contains values describing the location and orientation of a plane fitted to the 3D points represented by the terrain mesh's vertices.

• Slope (fittedPlane.slope): The slope (in degrees) of the fitted plane.
• Percent of variation explained / Var. explained (fittedPlane.pctExplained): A measure of "fitness" of the plane. That is, this measure indicates how close the terrain's vertices are to the fitted plane.
• Centroid (fittedPlane.centroid): A THREE.Vector3 instance representing the center of the fitted plane in 3D space.
• Normal (fittedPlane.normal): A THREE.Vector3 instance representing the normal vector of the fitted plane.