Appearance
@jdultra/ultra-globe / TopologyEngine
Class: TopologyEngine
Defined in: topology/TopologyEngine.d.ts:18
Flexible topology engine for rule-driven and query-driven pair evaluation across one or more vector layers.
The engine lazily builds mutable per-layer spatial indexes, keeps them synchronized through vector layer feature-change listeners, performs lightweight bounding-box candidate pruning, and then delegates exact topology truth to the existing math kernels in GeoMathUtils.
Rules preserve active pair state so only transitions emit callbacks:
- first observation as matching emits
enter - first observation as non-matching emits nothing
- active to inactive emits
exit - deletion of an active source or target also emits
exit
The class is exported as part of the public UltraGlobe API from src/ultraglobe.js.
Constructors
Constructor
new TopologyEngine(
options?):TopologyEngine
Defined in: topology/TopologyEngine.d.ts:22
Parameters
options?
TopologyEngineOptions
Engine-wide configuration.
Returns
TopologyEngine
Properties
options
options:
Object
Defined in: topology/TopologyEngine.d.ts:23
Methods
addContainmentRule2D()
addContainmentRule2D(
sourceLayer,targetLayer,options?):string
Defined in: topology/TopologyEngine.d.ts:88
Register a 2D containment rule where source features are treated as containers and target features are treated as contained candidates.
Parameters
sourceLayer
VectorLayer
Source container layer.
targetLayer
VectorLayer
Target contained layer.
options?
Omit<TopologyRuleDefinition, "type" | "mode" | "relation" | "sourceLayer" | "targetLayer" | "threshold">
Rule options.
Returns
string
The registered rule identifier.
addContainmentRule3D()
addContainmentRule3D(
sourceLayer,targetLayer,options?):string
Defined in: topology/TopologyEngine.d.ts:97
Register a 3D containment rule.
Parameters
sourceLayer
VectorLayer
Source container layer.
targetLayer
VectorLayer
Target contained layer.
options?
Omit<TopologyRuleDefinition, "type" | "mode" | "relation" | "sourceLayer" | "targetLayer" | "threshold">
Rule options.
Returns
string
The registered rule identifier.
addDistanceRule2D()
addDistanceRule2D(
sourceLayer,targetLayer,threshold,options?):string
Defined in: topology/TopologyEngine.d.ts:107
Register a 2D distance-threshold rule.
Parameters
sourceLayer
VectorLayer
Source layer.
targetLayer
VectorLayer
Target layer.
threshold
number
Inclusive distance threshold.
options?
Omit<TopologyRuleDefinition, "type" | "mode" | "relation" | "sourceLayer" | "targetLayer" | "threshold">
Rule options.
Returns
string
The registered rule identifier.
addDistanceRule3D()
addDistanceRule3D(
sourceLayer,targetLayer,threshold,options?):string
Defined in: topology/TopologyEngine.d.ts:117
Register a 3D distance-threshold rule.
Parameters
sourceLayer
VectorLayer
Source layer.
targetLayer
VectorLayer
Target layer.
threshold
number
Inclusive distance threshold.
options?
Omit<TopologyRuleDefinition, "type" | "mode" | "relation" | "sourceLayer" | "targetLayer" | "threshold">
Rule options.
Returns
string
The registered rule identifier.
addRule()
addRule(
ruleDefinition):string
Defined in: topology/TopologyEngine.d.ts:127
Register a topology rule using the normalized shared rule schema.
Registered rules keep active pair state internally and only emit transition callbacks when a pair enters or exits the matching set.
Parameters
ruleDefinition
TopologyRuleDefinition
Rule definition.
Returns
string
The registered rule identifier.
destroy()
destroy():
void
Defined in: topology/TopologyEngine.d.ts:174
Remove listeners, clear indexes and rules, and permanently dispose the engine instance.
Returns
void
dropIndex()
dropIndex(
vectorLayer):TopologyEngine
Defined in: topology/TopologyEngine.d.ts:60
Drop a layer index and unsubscribe from its change notifications.
If a rule or query later references the layer again, the index is rebuilt lazily.
Parameters
vectorLayer
VectorLayer
Layer whose index should be removed.
Returns
TopologyEngine
The engine instance.
evaluateRules()
evaluateRules(
options?):TopologyEvaluateSummary
Defined in: topology/TopologyEngine.d.ts:160
Evaluate registered rules.
By default, the engine only evaluates rules touched by pending dirty-layer changes gathered from subscribed vector layers. Passing forceFull: true re-evaluates the complete source/target pair space for the selected rules.
Parameters
options?
TopologyEvaluateOptions
Evaluation options.
Returns
TopologyEvaluateSummary
Evaluation summary.
getRule()
getRule(
ruleId):TopologyRule|null
Defined in: topology/TopologyEngine.d.ts:143
Return a public snapshot of a registered rule.
Parameters
ruleId
string
Rule identifier.
Returns
TopologyRule | null
Rule snapshot or null when not found.
getRules()
getRules():
TopologyRule[]
Defined in: topology/TopologyEngine.d.ts:149
Return public snapshots of all registered rules.
Returns
TopologyRule[]
All registered rule snapshots.
hasIndex()
hasIndex(
vectorLayer):boolean
Defined in: topology/TopologyEngine.d.ts:67
Test whether a layer currently has an allocated index.
Parameters
vectorLayer
VectorLayer
Layer to test.
Returns
boolean
True when the layer already has an index instance.
invalidateLayer()
invalidateLayer(
vectorLayer,options?):TopologyEngine
Defined in: topology/TopologyEngine.d.ts:78
Explicitly mark a layer as stale so its feature records will be re-resolved from the layer before the next query or rule evaluation.
This is useful when callers know data changed outside the normal feature-change listener pathway.
Parameters
vectorLayer
VectorLayer
Layer to invalidate.
options?
TopologyInvalidateOptions
Invalidation details.
Returns
TopologyEngine
The engine instance.
prepareIndex()
prepareIndex(
vectorLayer,options?):TopologyEngine
Defined in: topology/TopologyEngine.d.ts:51
Build or refresh a mutable spatial index for a vector layer immediately.
Indexes are normally built lazily when a rule or query first touches a layer. Calling this method is useful when callers want deterministic warm-up or to tune per-layer spatial hash parameters ahead of time.
Parameters
vectorLayer
VectorLayer
Layer to index.
options?
TopologyLayerIndexOptions
Optional per-layer index tuning.
Returns
TopologyEngine
The engine instance.
query()
query(
queryDefinition):TopologyQueryMatch[]
Defined in: topology/TopologyEngine.d.ts:170
Execute a one-shot pair topology query using the same normalization, candidate collection, and exact evaluation core that rules use internally.
Only matching pairs are returned.
Parameters
queryDefinition
TopologyQueryDefinition
Query definition.
Returns
TopologyQueryMatch[]
Matching source/target pairs.
removeRule()
removeRule(
ruleId):boolean
Defined in: topology/TopologyEngine.d.ts:136
Remove a previously registered rule.
Removing a rule clears its internal active pair state but does not emit exit callbacks for teardown.
Parameters
ruleId
string
Rule identifier.
Returns
boolean
True when a rule was removed.