UNPKG

@arcgis/core

Version:

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

432 lines (430 loc) • 28.5 kB
import type Graphic from "../../Graphic.js"; import type Extent from "../../geometry/Extent.js"; import type SceneLayer from "../../layers/SceneLayer.js"; import type FeatureFilter from "../../layers/support/FeatureFilter.js"; import type FeatureSet from "../../rest/support/FeatureSet.js"; import type Query from "../../rest/support/Query.js"; import type LayerView from "./LayerView.js"; import type { ResourceHandle } from "../../core/Handles.js"; import type { AbortOptions } from "../../core/promiseUtils.js"; import type { QueryProperties } from "../../rest/support/Query.js"; import type { ObjectId } from "../types.js"; import type { LayerViewHighlightOptions } from "./types.js"; import type { FeatureFilterProperties } from "../../layers/support/FeatureFilter.js"; import type { LayerViewProperties } from "./LayerView.js"; export interface SceneLayerViewProperties extends LayerViewProperties, Partial<Pick<SceneLayerView, "maximumNumberOfFeatures">> { /** * Applies a client-side [FeatureFilter](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureFilter/) to the displayed data. * Only the features that satisfy the filter are displayed. The fields to be used for the filter must be present in the layer view's * [availableFields](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#availableFields) list. * * > [!WARNING] * > * > **Known Limitations** * > * > The [FeatureFilter.timeExtent](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureFilter/#timeExtent) property is not supported on a SceneLayerView filter. * > For 3D object scene layers, only spatial filters with [FeatureFilter.spatialRelationship](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureFilter/#spatialRelationship) * > set to `contains`, `intersects` or `disjoint` are supported. * * @since 4.11 */ filter?: FeatureFilterProperties | null; } /** * Represents the [LayerView](https://developers.arcgis.com/javascript/latest/references/core/views/layers/LayerView/) of a [SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) * after it has been added to a [Map](https://developers.arcgis.com/javascript/latest/references/core/Map/) in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). * * The SceneLayerView is responsible for streaming and rendering a [SceneLayer's](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) * features in the [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). The [methods](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#queryExtent) * in the SceneLayerView provide developers with the ability to query loaded features. See the * code snippets in the [methods](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#queryExtent) below for examples of how to access client-side graphics from the * view. * * Features in a [SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) are loaded progressively, * starting from coarse representations that are refined to higher levels of detail as * necessary for close-up views. * * Queries on the SceneLayerView will be executed against features that have been loaded for the current view. * This means that only visible features are guaranteed to be available once the layer has finished updating. * At lower levels of detail, features may be omitted from rendering by the SceneLayerView, * and will therefore not be included in the results of queries. * This means that the query methods on the SceneLayerView should not be used when the intention is to query or search * within the whole dataset, instead the query methods on the [SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) should be used. * * To only execute a query once the loading of features has completed, applications can wait until the * [updating](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#updating) property of the SceneLayerView is `false`. Batched Queries with num and start * should only be used when this SceneLayerView is not updating, otherwise the result is undefined. * * @since 4.3 * @see [SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) * @see [Sample - Query SceneLayerView](https://developers.arcgis.com/javascript/latest/sample-code/layers-scenelayerview-query/) * @see [Working with scene layers guide topic](https://developers.arcgis.com/javascript/latest/working-with-scene-layers/) */ export default abstract class SceneLayerView extends LayerView { /** * A list of attribute fields fetched for each feature including fields required for layer * [rendering](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#renderer) and additional fields defined on the * [SceneLayer.outFields](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#outFields). * The availableFields is populated when the layer view is finished [updating](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#updating). Use this list when * querying features on the [client](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#queryFeatures). * * @since 4.12 * @see [SceneLayer.outFields](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#outFields) */ get availableFields(): string[]; /** * Applies a client-side [FeatureFilter](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureFilter/) to the displayed data. * Only the features that satisfy the filter are displayed. The fields to be used for the filter must be present in the layer view's * [availableFields](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#availableFields) list. * * > [!WARNING] * > * > **Known Limitations** * > * > The [FeatureFilter.timeExtent](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureFilter/#timeExtent) property is not supported on a SceneLayerView filter. * > For 3D object scene layers, only spatial filters with [FeatureFilter.spatialRelationship](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FeatureFilter/#spatialRelationship) * > set to `contains`, `intersects` or `disjoint` are supported. * * @since 4.11 */ get filter(): FeatureFilter | null | undefined; set filter(value: FeatureFilterProperties | null | undefined); /** The scene layer being viewed. */ get layer(): SceneLayer; /** * The maximum number of features that can be displayed at a time. This setting currently only applies to * point scene layer views. By default, the maximum number of features is estimated automatically depending on the * symbology, geometry complexity, memory consumption and display quality profile. * * Changing this setting to a higher value may lead to a significant decrease in performance and increase in * memory usage. * * @since 4.11 */ accessor maximumNumberOfFeatures: number; /** * Signifies whether the maximum number of features has been exceeded. Not all features could be displayed * when this value is `true`. This setting currently only applies to point scene layer views. * * @since 4.11 */ get maximumNumberOfFeaturesExceeded(): boolean; /** * Creates query parameter object that can be used to fetch features as they are being * displayed. It sets the query parameter's [Query.outFields](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#outFields) * property to `["*"]` and [Query.returnGeometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#returnGeometry) to `true`. * The output spatial reference is set to the spatial reference of the view. The filter that currently * applies to the layer view is also incorporated in the returned query object. * * @returns The query object */ createQuery(): Query; /** * Highlights the given feature(s). * * @param target - The feature(s) to highlight. When passing a graphic or array of graphics, each feature must * have a valid `objectID`. You may alternatively pass one or more objectIDs as a single number or * an array. * @param options - An object with the following properties. * @returns Returns a highlight handler with a `remove()` method that * can be called to remove the highlight. * @since 4.4 * @see [SceneView.highlights](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#highlights) * @see [Sample: Highlight SceneLayer](https://developers.arcgis.com/javascript/latest/sample-code/highlight-scenelayer/) * @example * // Highlight features based on a layer query result * // This workflow is valid only if the scene layer has an associated feature layer * * // Add a new set of highlight options to the view's highlights collection * view.highlights.push({ * name: "oaks", * color: "forestgreen", * haloOpacity: 0.8, * fillOpacity: 0.3 * }); * * // A handler can be used to remove any previous highlight when applying a new one * let highlight; * * // Query for particualar features in the layer and then highlight them with the specified options * view.whenLayerView(sceneLayer).then((layerView) => { * let query = sceneLayer.createQuery(); * query.where = "type = 'Quercus'"; * * sceneLayer.queryFeatures(query).then((result) => { * // Remove any previous highlight, if it exists * highlight?.remove(); * // Apply the "oaks" highlight options to the corresponding tree features * highlight = layerView.highlight(result.features, { name: "oaks" }); * }) * }); * @example * // Use the default highlights collection to apply a highlight to features when you hover over them * * // A handler can be used to remove any previous highlight when applying a new one * let hoverHighlight; * * view.on("pointer-move", (event) => { * // Search for the first feature in the layer at the hovered location * view.hitTest(event).then((response) => { * if (response.results[0]) { * const graphic = response.results[0].graphic; * view.whenLayerView(graphic.layer).then((layerView) => { * // Remove any previous highlight, if it exists * hoverHighlight?.remove(); * // Highlight the hit features with the temporary highlight options, which are pre-configured for this use case * hoverHighlight = layerView.highlight(graphic, { name: "temporary" }); * }) * } * }) * }); */ highlight(target: Graphic | Graphic[] | number | number[], options?: LayerViewHighlightOptions): ResourceHandle; /** * Executes a [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) against features in the layer view and * returns the 3D [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) of features that satisfy the query. If query parameters are * not provided, the extent and count of all loaded features are returned. * * Read more about queries in the Query section of the [SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) class description. * * To query for the extent of features directly from a Scene Service rather than those * loaded for the current view, you must * use the [SceneLayer.queryExtent()](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#queryExtent) * method. * * For making attribute based queries on a SceneLayerView you need to specify the required fields * in the [SceneLayer.outFields](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#outFields) property of the SceneLayer to ensure that attribute values are * available on the client for querying. You can use [availableFields](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#availableFields) * to inspect which fields are available on the client. * * > [!WARNING] * > * > **Known Limitations** * > * > Spatial queries have the same limitations as those listed in the [projectOperator](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/projectOperator/) * > documentation. * > Spatial queries on 3D Object scene layer views use the [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) of the feature and * > not the footprint when calculating the spatial relationship with the [query geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry). * > This means that a feature might be returned from the query, even though its footprint is not in a spatial relationship with the geometry. * > Currently only `intersects`, `contains`, and `disjoint` [spatialRelationships](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship) are supported on spatial * > [queries](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/). * > Spatial queries are not currently supported if the SceneLayerView has any of the following [SpatialReferences](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/): * > - GDM 2000 (4742) - Malaysia * > - Gsterberg (Ferro) (8042) - Austria/Czech Republic * > - ISN2016 (8086) - Iceland * > - SVY21 (4757) - Singapore * * @param query - Specifies the attributes and spatial filter of the query. * When no parameters are passed to this method, all features on the client are returned. * @param options - An object with the following properties. * @returns When resolved, returns the extent and count of the features * that satisfy the input query. See the object specification table below for details. * Property | Type | Description * ---------|------|------------- * count | Number | The number of features that satisfy the input query. * extent | [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) | The extent of the features that satisfy the query. * @example * let layer = new SceneLayer({ * url: ssUrl // points to a Scene Service layer url * }); * * view.whenLayerView(layer).then(function(layerView){ * reactiveUtils.whenOnce(() => !layerView.updating) * .then(function() { * return layerView.queryExtent(); * }) * .then(function(results) { * view.goTo(results.extent); // go to the extent of all the graphics in the layer view * }); * }); */ queryExtent(query?: QueryProperties | null | undefined, options?: AbortOptions): Promise<{ count: number; extent: Extent | null; }>; /** * Executes a [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) against features in the layer view * and returns the number of features that satisfy the query. If query parameters are not provided, * the count of all loaded features is returned. Read more about queries in the Query * section of the [SceneLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/) class description. * * To query for the count of features directly from a Scene Service rather than those * loaded for the current view, you must * use the [SceneLayer.queryFeatureCount()](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#queryFeatureCount) * method. * * For making attribute based queries on a SceneLayerView you need to specify the required fields * in the [SceneLayer.outFields](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#outFields) property of the SceneLayer to ensure that attribute values are * available on the client for querying. You can use [availableFields](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#availableFields) * to inspect which fields are available on the client. * * > [!WARNING] * > * > **Known Limitations** * > * > Spatial queries have the same limitations as those listed in the [projectOperator](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/projectOperator/) * > documentation. * > Spatial queries on 3D Object scene layer views use the [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) of the feature and * > not the footprint when calculating the spatial relationship with the [query geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry). * > This means that a feature might be returned from the query, even though its footprint is not in a spatial relationship with the geometry. * > Currently only `intersects`, `contains`, and `disjoint` [spatialRelationships](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship) are supported on spatial * > [queries](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/). * > Spatial queries are not currently supported if the SceneLayerView has any of the following [SpatialReferences](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/): * > - GDM 2000 (4742) - Malaysia * > - Gsterberg (Ferro) (8042) - Austria/Czech Republic * > - ISN2016 (8086) - Iceland * > - SVY21 (4757) - Singapore * * @param query - Specifies the attributes and spatial filter of the query. * When no parameters are passed to this method, all features on the client are returned. To only return features * visible in the view, set the `geometry` parameter in the query object to the view's visible area. * @param options - An object with the following properties. * @returns When resolved, returns the number of features satisfying the query. * @example * let layer = new SceneLayer({ * url: ssUrl // points to a Scene Service layer url * }); * * view.whenLayerView(layer).then(function(layerView){ * reactiveUtils.whenOnce(() => !layerView.updating) * .then(function() { * return layerView.queryFeatureCount(); * }) * .then(function(count) { * console.log(count); // prints the number of client-side graphics that are currently loaded * }); * }); */ queryFeatureCount(query?: QueryProperties | null | undefined, options?: AbortOptions): Promise<number>; /** * Executes a [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) against features in the layer view * and returns a [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/). If query parameters are not provided, * all loaded features are returned. * * To execute a query against all the features in a Scene Service rather than only those loaded for the current view, * you must use the [SceneLayer.queryFeatures()](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#queryFeatures) * method. * * For making attribute based queries on a SceneLayerView you need to specify the required fields * in the [SceneLayer.outFields](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#outFields) property of the SceneLayer to ensure that * attribute values are available on the client for querying. You can use [availableFields](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#availableFields) * to inspect which fields are available on the client. * * Feature queries support returning Mesh geometries when `returnGeometry` is set to `true` in the query * (the default). The returned geometries are initially not loaded to avoid unnecessary memory consumption. They * need to be loaded using [Mesh.load()](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#load) before their vertex attributes are available. Unloaded Mesh * geometries do have an [Mesh.extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/#extent) property that can be used to determine the bounding box of the * geometry before loading it fully. The Mesh `load()` will fail if the data being referenced by the Mesh is no * longer available, for example if it is no longer in the view. * * > [!WARNING] * > * > **Known Limitations** * > * > Spatial queries have the same limitations as those listed in the * > [projectOperator](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/projectOperator/) documentation. * > Spatial queries on 3D Object scene layer views use the [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) of the feature and * > not the footprint when calculating the spatial relationship with the * > [query geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry). This means that a feature might be returned from * > the query, even though its footprint is not in a spatial relationship with the geometry. * > Currently only `intersects`, `contains`, and `disjoint` * > [spatialRelationships](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship) are supported on spatial * > [queries](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/). * > Spatial queries are not currently supported if the SceneLayerView has any of the following * > [SpatialReferences](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/): * > - GDM 2000 (4742) - Malaysia * > - Gsterberg (Ferro) (8042) - Austria/Czech Republic * > - ISN2016 (8086) - Iceland * > - SVY21 (4757) - Singapore * > Returned mesh geometries only contain vertex positions and do not have normals, texture coordinates or materials. * * @param query - Specifies the attributes and spatial filter of the query. * When no parameters are passed to this method, all features on the client are returned along with their attributes * specified in [availableFields](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#availableFields). To only return features * visible in the view, set the `geometry` parameter in the query object to the view's visible area. * @param options - An object with the following properties. * @returns When resolved, a [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) is returned. * The set will be empty if zero results are found. * @example * let layer = new SceneLayer({ * url: ssUrl // points to a Scene Service layer url * }); * * // returns loaded features from the layer view that match the query * let query = new Query(); * query.objectIds = [10, 125, 126, 200, 201]; * query.outFields = ["NAME", "STATE_ABBR", "POP04"]; * * view.whenLayerView(layer).then(function(layerView){ * reactiveUtils.whenOnce(() => !layerView.updating) * .then(function() { * return layerView.queryFeatures(query); * }) * .then(function(result) { * console.log(result.features); // prints the client-side graphics to the console * }); * }); * @example * let layer = new SceneLayer({ * url: ssUrl // points to a Scene Service layer url * }); * * const layerView = await view.whenLayerView(layer); * await reactiveUtils.whenOnce(() => !layerView.updating); * * // returns all loaded features from the layer view * const result = await layerView.queryFeatures() * console.log(result.features); // prints all loaded client-side graphics to the console */ queryFeatures(query?: QueryProperties | null | undefined, options?: AbortOptions): Promise<FeatureSet>; /** * Executes a [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) against features in * the layer view and returns an array of the ObjectIDs of features that satisfy the input query. If * query parameters are not provided, the ObjectIDs of all loaded features are returned. * * To query for ObjectIDs of features directly from a Scene Service rather than those * loaded for the current view, you must * use the [SceneLayer.queryObjectIds()](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#queryObjectIds) * method. * * For making attribute based queries on a SceneLayerView you need to specify the required fields * in the [SceneLayer.outFields](https://developers.arcgis.com/javascript/latest/references/core/layers/SceneLayer/#outFields) property of the SceneLayer to ensure that attribute values are * available on the client for querying. You can use [availableFields](https://developers.arcgis.com/javascript/latest/references/core/views/layers/SceneLayerView/#availableFields) * to inspect which fields are available on the client. * * > [!WARNING] * > * > **Known Limitations** * > * > Spatial queries have the limitations listed in the [projectOperator](https://developers.arcgis.com/javascript/latest/references/core/geometry/operators/projectOperator/) * > documentation. * > Spatial queries on 3D Object scene layer views use the [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) of the feature and * > not the footprint when calculating the spatial relationship with the [query geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry). * > This means that a feature might be returned from the query, even though its footprint is not in a spatial relationship with the geometry. * > Currently only `intersects`, `contains`, and `disjoint` [spatialRelationships](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship) are supported on spatial * > [queries](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/). * > Spatial queries are not currently supported if the SceneLayerView has any of the following [SpatialReferences](https://developers.arcgis.com/javascript/latest/references/core/geometry/SpatialReference/): * > - GDM 2000 (4742) - Malaysia * > - Gsterberg (Ferro) (8042) - Austria/Czech Republic * > - ISN2016 (8086) - Iceland * > - SVY21 (4757) - Singapore * * @param query - Specifies the attributes of the query. * If query parameters are not provided, all loaded features are returned. * @param options - An object with the following properties. * @returns When resolved, returns an array of numbers representing the ObjectIDs of the features * satisfying the query. * @example * let layer = new SceneLayer({ * url: ssUrl // points to a Scene Service layer url * }); * * // returns all the Ids from the features in the layer view * view.whenLayerView(layer).then(function(layerView){ * return layerView.queryObjectIds(); * }).then(function(ids){ * console.log(ids); // prints the ids of all the client-side graphics to the console * }); */ queryObjectIds(query?: QueryProperties | null | undefined, options?: AbortOptions): Promise<ObjectId[]>; }