org.critterai.nmgen
Class OpenHeightfieldBuilder

java.lang.Object
  extended by org.critterai.nmgen.OpenHeightfieldBuilder

public final class OpenHeightfieldBuilder
extends Object

Builds an open heightfield from the solid data contained by an SolidHeightfield. It does this by locating and creating spans representing the area above spans within the source field that have a specified flag.

Options are provided to generate neighbor, distance field, and region information for the open span data

Example of a fully formed open heightfield. (I.e. With region information.) Only the floor of the spans is shown.

See Also:
Introduction to Height Fields, Region Generation, OpenHeightfield, OpenHeightSpan

Constructor Summary
OpenHeightfieldBuilder(int minTraversableHeight, int maxTraversableStep, int traversableAreaBorderSize, int smoothingThreshold, int filterFlags, boolean useConservativeExpansion, ArrayList<IOpenHeightFieldAlgorithm> regionAlgorithms)
          Constructor
 
Method Summary
 void blurDistanceField(OpenHeightfield field)
          Performs a smoothing pass on the distance field data.
 OpenHeightfield build(SolidHeightfield sourceField, boolean performFullGeneration)
          Builds an OpenHeightfield from the provided SolidHeightfield based on the configuration settings.
 void generateDistanceField(OpenHeightfield field)
          Generates distance field information.
 void generateNeighborLinks(OpenHeightfield field)
          Generates axis-neighbor link information for all spans in the field.
 void generateRegions(OpenHeightfield field)
          Groups spans into contiguous regions using an watershed based algorithm.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OpenHeightfieldBuilder

public OpenHeightfieldBuilder(int minTraversableHeight,
                              int maxTraversableStep,
                              int traversableAreaBorderSize,
                              int smoothingThreshold,
                              int filterFlags,
                              boolean useConservativeExpansion,
                              ArrayList<IOpenHeightFieldAlgorithm> regionAlgorithms)
Constructor

Parameters:
minTraversableHeight - Represents the minimum floor to ceiling height that will still allow the floor area to be considered walkable.

Permits detection of overhangs in the geometry which make the geometry below become unwalkable.

Constraints: > 0

maxTraversableStep - Represents the maximum ledge height that is considered to still be walkable.

Prevents minor deviations in height from improperly showing as obstructions. Permits detection of stair-like structures, curbs, etc.

Constraints: >= 0

traversableAreaBorderSize - Represents the closest any part of the navmesh can get to an obstruction in the source mesh.

Usually set to the maximum bounding radius of entities utilizing the navmesh for navigation decisions.

Constraints: >= 0

smoothingThreshold - The amount of smoothing to be performed when generating the distance field.

This value impacts region formation and border detection. A higher value results in generally larger regions and larger border sizes. A value of zero will disable smoothing.

Constraints: 0 <= value <= 4

filterFlags - The flags used to determine which spans from the source SolidHeightfield should be used to build the OpenHeightfield. Only those spans which whose flags exactly match the filter flag will be considered for inclusion in the generated open field.

Note: Spans from the source field which do not match the filter flags are still taken into account as height obstructions.

useConservativeExpansion - Applies extra algorithms to regions to help prevent poorly formed regions from forming.

If the navigation mesh is missing sections that should be present, then enabling this feature will likely fix the problem

Enabling this feature significantly increased processing cost.

regionAlgorithms - A list of the algorithms to run after initial region generation is complete. The algorithms will be run in the order of the list.
Method Detail

blurDistanceField

public void blurDistanceField(OpenHeightfield field)
Performs a smoothing pass on the distance field data.

This operation depends on distance field information. So the generateDistanceField(OpenHeightfield) operation must be run before this operation.

This operation does not need to be run if the build operation was run with performFullGeneration set to TRUE.

Parameters:
field - A populated open height field with distance field data already generated.

build

public OpenHeightfield build(SolidHeightfield sourceField,
                             boolean performFullGeneration)
Builds an OpenHeightfield from the provided SolidHeightfield based on the configuration settings.

Parameters:
sourceField - The solid field to derive the open field from.
performFullGeneration - If TRUE, neighbor link, distance field (including blurring), and region information will be generated. If FALSE, only the spans will be generated.

generateDistanceField

public void generateDistanceField(OpenHeightfield field)
Generates distance field information. The OpenHeightSpan.distanceToBorder() information is generated for all spans in the field.

A boundary is a span with a missing neighbor. It will always have a distance value of zero. A span is not a boundary if is has 4 neighbors. Its boundary distance value will be higher the further it is from a boundary span.

All distance values are relative and do not represent explicit distance values (such as grid unit distance). The algorithm which is used results in an approximation only. It is not exhaustive.

This operation depends on neighbor information. So the generateNeighborLinks(OpenHeightfield) operation must be run before this operation.

This operation does not need to be run if the build operation was run with performFullGeneration set to TRUE.

The data generated by this operation is required by blurDistanceField(OpenHeightfield) and generateRegions(OpenHeightfield)

Parameters:
field - A field with spans and neighbor information already generated.

generateNeighborLinks

public void generateNeighborLinks(OpenHeightfield field)
Generates axis-neighbor link information for all spans in the field. This information is required for algorithms which perform neighbor searches.

After this operation is run, the OpenHeightSpan.getNeighbor(int) operation can be used for neighbor searches.

This operation does not need to be run if the build operation was run with performFullGeneration set to TRUE.

The data generated by this operation is required by generateDistanceField(OpenHeightfield)

Parameters:
field - A field already loaded with span information.
See Also:
Neighbor Searches

generateRegions

public void generateRegions(OpenHeightfield field)
Groups spans into contiguous regions using an watershed based algorithm.

This operation depends on neighbor and distance field information. So the generateNeighborLinks(OpenHeightfield) and generateDistanceField(OpenHeightfield) operations must be run before this operation.

This operation does not need to be run if the build operation was run with performFullGeneration set to TRUE.

Parameters:
field - A field with span, neighbor, and distance information fully generated.


Project Home and Source Code

Copyright 2010 Stephen Pratt. All rights reserved. Use is subject to license terms.