Map Filtering

Map filtering constrains map content (and related data panels) to a geometric area plus optional source scoping (layer, shape, region, record location, raw GeoJSON, or user geolocation). Only one geometry filter definition is active at a time. You can temporarily disable it, re‑enable it, or clear it entirely.

setMapFilter

Create or replace the current active map filter.

Parameter: filter (MapGeometryFilter)

Field	Type	Required	Description
filterName	string	Yes	Display / audit label for the filter.
mapFilterId	string	Yes	Unique stable identifier (e.g. crypto.randomUUID()).
filterType	MapFilterType	Yes	Defines the source/context of the filter geometry & properties.
filteredObjectName	string	Yes	Human friendly name of the target entity (layer, shape, region, etc.).
geometry	Polygon | MultiPolygon	Yes	WGS84 ([lon, lat]) geometry used for spatial filtering.
bufferDistance	number	Yes	Distance to expand outward from geometry (0 for none).
distanceUnit	DistanceUnits	Yes	Unit of the buffer (meters, kilometers, miles).
filterProperties	LayerMapFilter | ShapeMapFilter | RegionMapFilter | GeoJSONMapFilter | RecordLocationMapFilter | GeoLocationFilter | undefined	Conditional	Additional metadata required for specific filterType variants.
booleanOperator	MapFilterBooleanOperator	Optional	Logical combination when multiple internal shapes/components are present.
isPreconfigured	boolean	Optional	Flags if loaded from saved configuration instead of created ad-hoc.

Enum: MapFilterType

Value	Meaning
layer	Filter tied to a map layer (optionally sublayer instances).
shape	Based on existing authored shape(s).
region	Uses predefined region geometry.
geojson	Raw ad-hoc GeoJSON geometry.
recordlocation	Derived from record(s) location points.
geolocation	User/device current location (often buffered).

Enum: MapFilterBooleanOperator

Value	Effect
union	Combine areas inclusively.
subtract	Subtract subsequent area(s) from prior.
intersect	Only overlapping portions retained.

Enum: DistanceUnits

Value	Notes
meters	SI base unit; fine-grained buffers.
kilometers	Larger regional extents.
miles	Imperial measure; ensure consistency with UI units.

Conditional field guidance

• Use filterProperties.layerId (and optional subLayerInstanceIds[]) when filterType = 'layer'.
• Provide shapeIds[] when filterType = 'shape'.
• Provide regionIds[] when filterType = 'region'.
• Supply a simple { sourceName?: string } when filterType = 'geojson' (geometry carries actual shape).
• Use recordIds[] when filterType = 'recordlocation'.
• Provide { center: [lon, lat] } when filterType = 'geolocation' (often with non‑zero buffer).

Geometry

Keep vertex count modest (< 5k) to avoid performance degradation. For large drawn polygons, consider client-side simplification before passing to setMapFilter.

Usage (simple polygon):

const filter: MapGeometryFilter = {
	filterName: "Focus Area - West",
	mapFilterId: crypto.randomUUID(),
	filterType: "geojson",
	filteredObjectName: "Ad-hoc Polygon",
	filterProperties: { sourceName: "user-draw" },
	booleanOperator: "AND",
	bufferDistance: 0,
	distanceUnit: "meters",
	geometry: {
		type: "Polygon",
		coordinates: [
			[[115.8376,-32.1152],[115.8385,-32.1158],[115.8403,-32.1172],[115.8376,-32.1152]]
		]
	}
};
await control.setMapFilter(filter);

Usage (layer scoped – using previously selected sublayer instance):

// Assume a form input already stores the chosen sublayerInstanceId (user picked a layer in earlier UI step)
const instanceIdInput = document.getElementById('selectedInstanceId') as HTMLInputElement;
const sublayerInstanceId = instanceIdInput.value; // e.g. "fba870dc-284d-4b7d-a37f-84ed3a9ada8d"

// Retrieve enabled instances so we can resolve the parent layerId & friendly name
const enabledInstances = await control.getEnabledSublayerInstances();
const targetInstance = enabledInstances.find(i => i.sublayerInstanceId === sublayerInstanceId);
if (!targetInstance) {
	throw new Error('Selected sublayer instance not found/enabled');
}

// We need the parent layerId. If not exposed directly, derive via gallery lookup.
// (Adjust if your API returns layerId on the instance object.)
// Fetch gallery layers to map sublayerId -> layerId
const galleryLayers = await control.getGalleryLayers();
const parentLayer = galleryLayers.find(l => l.subLayers?.some(sl => sl.sublayerId === targetInstance.sublayerId));
if (!parentLayer) {
	throw new Error('Parent layer could not be resolved');
}

await control.setMapFilter({
	filterName: `Focus area for ${targetInstance.sublayerName}`,
	mapFilterId: crypto.randomUUID(),
	filterType: 'layer',
	filteredObjectName: parentLayer.layerName,
	filterProperties: {
		layerId: parentLayer.layerId,
		subLayerInstanceIds: [sublayerInstanceId]
	},
	bufferDistance: 0,
	distanceUnit: 'meters',
	geometry: {
		type: 'Polygon',
		coordinates: [
			[[115.83,-32.11],[115.85,-32.11],[115.85,-32.13],[115.83,-32.13],[115.83,-32.11]]
		]
	}
});

Instance vs Layer IDs

Use getEnabledSublayerInstances() to obtain the user-selected instance id, then map back to its layerId via getGalleryLayers() if the instance object does not already include it. Keep the instance id list minimal—filtering multiple instances simultaneously may broaden results.

note

Calling setMapFilter again overwrites the previous definition. Apply modest vertex counts for performance. Buffer is outward only.

---

disableMapFilter

Disables the current map filter while retaining its definition for later reactivation.

Parameters: none

Usage:

control.disableMapFilter();

---

enableMapFilter

Re-enables existing map filter(s).

Parameters: none

Usage:

control.enableMapFilter();

---

clearMapFilter

Completely removes the current map filter(s). Cannot be re-enabled without calling setMapFilter again.

Parameters: none

Usage:

control.clearMapFilter();

---