@itwin/core-common/lib/esm/MapLayerSettings.d.ts

iTwin.js components common to frontend and backend

/** @packageDocumentation
 * @module MapLayers
 */
import { Id64String } from "@itwin/core-bentley";
import { BackgroundMapProvider, BackgroundMapProviderProps, BackgroundMapType } from "./BackgroundMapProvider";
import { DeprecatedBackgroundMapProps } from "./BackgroundMapSettings";
/** The current set of supported map layer formats.
 * In order to be displayed, a corresponding format must have been registered in the [MapLayerFormatRegistry]($frontend)
 * @public
 */
export type ImageryMapLayerFormatId = "ArcGIS" | "BingMaps" | "MapboxImagery" | "TileURL" | "WMS" | "WMTS";
/** @public */
export type SubLayerId = string | number;
/**
 * Type for map layer provider array property.
 * @beta
 */
export type MapLayerProviderArrayProperty = number[] | string[] | boolean[];
/**
 * Type for map layer provider properties.
 * @beta
 */
export interface MapLayerProviderProperties {
    [key: string]: number | string | boolean | MapLayerProviderArrayProperty;
}
/** JSON representation of the settings associated with a map sublayer included within a [[MapLayerProps]].
 * A map sub layer represents a set of objects within the layer that can be controlled separately.  These
 * are produced only from map servers that produce images on demand and are not supported by tiled (cached) servers.
 * @see [[MapLayerProps]]
 * @public
 */
export interface MapSubLayerProps {
    name: string;
    title?: string;
    visible?: boolean;
    id?: SubLayerId;
    parent?: SubLayerId;
    children?: SubLayerId[];
}
/** Normalized representation of a [[MapSubLayerProps]] for which values
 * have been validated and default values have been applied where explicit values not defined.
 * A map sub layer represents a set of objects within the layer that can be controlled separately.  These
 * are produced only from map servers that produce images on demand and are not supported by tiled (cached) servers.
 * This class can represent a hierarchy, in this case a sub layer is visible only if all its ancestors are also visible.
 * @see [[MapLayerSettings]]
 * @public
 */
export declare class MapSubLayerSettings {
    /** Typically Name is a single word used for machine-to-machine communication while the Title is for the benefit of humans (WMS) */
    readonly name: string;
    /** Title. */
    readonly title?: string;
    /** If true the sub layer is visible.  If part of a hierarchy, a sub layer is visible only if its ancestors are also visible. */
    readonly visible: boolean;
    /** A unique string or number that may be used to identify the sub layer (ArcGIS) */
    readonly id: SubLayerId;
    /** One or more sublayer children */
    readonly children?: SubLayerId[];
    /** sublayer parent. */
    readonly parent?: SubLayerId;
    constructor(name: string, title?: string, visible?: boolean, id?: SubLayerId, parent?: SubLayerId, children?: SubLayerId[]);
    /** Construct from JSON, performing validation and applying default values for undefined fields. */
    static fromJSON(json: MapSubLayerProps): MapSubLayerSettings;
    toJSON(): MapSubLayerProps;
    /** Creating a copy of this MapSubLayer, optionally modifying some if its properties */
    clone(changedProps: Partial<MapSubLayerProps>): MapSubLayerSettings;
    /** @internal */
    displayMatches(other: MapSubLayerSettings): boolean;
    /** return true if this sublayer is named. */
    get isNamed(): boolean;
    /** return true if this sublayer is a leaf (has no children) */
    get isLeaf(): boolean;
    /** return true if this sublayer is an unnamed group */
    get isUnnamedGroup(): boolean;
    /** return a string representing this sublayer id (converting to string if underlying id is number) */
    get idString(): string;
}
/** JSON representation of properties common to both [[ImageMapLayerProps]] and [[ModelMapLayerProps]].
 * @see [[MapImageryProps]]
 * @public
 */
export interface CommonMapLayerProps {
    /** Controls visibility of layer. Defaults to 'true'. */
    visible?: boolean;
    /** A user-friendly name for the layer. */
    name: string;
    /** A transparency value from 0.0 (fully opaque) to 1.0 (fully transparent) to apply to map graphics when drawing,
     * or false to indicate the transparency should not be overridden.
     * Default value: 0.
     */
    transparency?: number;
    /** True to indicate background is transparent.
     * Default: true.
     */
    transparentBackground?: boolean;
}
/** JSON representation of an [[ImageMapLayerSettings]].
 * @see [[MapImagerySettings]].
 * @see [[ImageryMapLayerFormatId]].
 * @public
 */
export interface ImageMapLayerProps extends CommonMapLayerProps {
    /** URL */
    url: string;
    /** Identifies the map layers source.*/
    formatId: string;
    /** Source layers. If undefined all layers are displayed. */
    subLayers?: MapSubLayerProps[];
    /** Access Key for the Layer, like a subscription key or access token.
     * ###TODO This does not belong in the props object. It should never be persisted.
     */
    /** @internal */
    accessKey?: MapLayerKey;
    /** @internal */
    modelId?: never;
    /** List of query parameters that will get appended to the source.
     * @beta
    */
    queryParams?: {
        [key: string]: string;
    };
    /** Properties specific to the map layer provider.
     * @beta
    */
    properties?: MapLayerProviderProperties;
}
/** The target onto which to drape a model map layer.
 * @beta
 */
export declare enum ModelMapLayerDrapeTarget {
    /** Drape only onto the globe. */
    Globe = 1,
    /** Drape only onto all attached reality data. */
    RealityData = 2,
    /** Drape only onto all models within the iModel. */
    IModel = 4
}
/** JSON representation of a [[ModelMapLayerSettings]].
 * @see [[MapImagerySettings]].
 * @public
 */
export interface ModelMapLayerProps extends CommonMapLayerProps {
    /** The Id of the [GeometricModel]($backend) containing the geometry to be drawn by the layer. */
    modelId: Id64String;
    /** Specifies the target onto which to drape this model map layer. Defaults to [ModelMapLayerDrapeTarget.Globe]($common).
     * @beta
     */
    drapeTarget?: ModelMapLayerDrapeTarget;
    /** @internal */
    url?: never;
    /** @internal */
    formatId?: never;
    /** @internal */
    subLayers?: never;
    /** @internal */
    accessKey?: never;
}
/** JSON representation of a [[MapLayerSettings]].
 * @see [[MapImagerySettings]].
 * @public
 */
export type MapLayerProps = ImageMapLayerProps | ModelMapLayerProps;
/**
 * stores key-value pair to be added to all requests made involving map layer.
 * @public
 */
export interface MapLayerKey {
    key: string;
    value: string;
}
/** Abstract base class for normalized representation of a [[MapLayerProps]] for which values have been validated and default values have been applied where explicit values not defined.
 * This class is extended by [[ImageMapLayerSettings]] and [ModelMapLayerSettings]] to create the settings for image and model based layers.
 * One or more map layers may be included within [[MapImagerySettings]] object.
 * @see [[MapImagerySettings]]
 * @public
 */
export declare abstract class MapLayerSettings {
    readonly visible: boolean;
    readonly name: string;
    readonly transparency: number;
    readonly transparentBackground: boolean;
    abstract get allSubLayersInvisible(): boolean;
    abstract clone(changedProps: Partial<MapLayerProps>): MapLayerSettings;
    abstract toJSON(): MapLayerProps;
    /** @internal */
    protected constructor(name: string, visible?: boolean, transparency?: number, transparentBackground?: boolean);
    /** Create a map layer settings from its JSON representation. */
    static fromJSON(props: MapLayerProps): MapLayerSettings;
    /** @internal */
    protected _toJSON(): CommonMapLayerProps;
    /** @internal */
    protected cloneProps(changedProps: Partial<MapLayerProps>): CommonMapLayerProps;
    /** @internal */
    displayMatches(other: MapLayerSettings): boolean;
    /** Return a unique string identifying the layers source... The URL for image layer or modelID for model layer  */
    abstract get source(): string;
    /** @internal */
    matchesNameAndSource(name: string, source: string): boolean;
}
/** Normalized representation of a [[ImageMapLayerProps]] for which values have been validated and default values have been applied where explicit values not defined.
 * Image map layers are created from servers that produce images that represent map tiles.  Map layers map also be represented by models.
 * One or more map layers may be included within [[MapImagerySettings]] object.
 * @see [[MapImagerySettings]]
 * @see [[ModelMapLayerSettings]] for model based map layer settings.
 * @public
 */
export declare class ImageMapLayerSettings extends MapLayerSettings {
    readonly formatId: string;
    readonly url: string;
    userName?: string;
    password?: string;
    accessKey?: MapLayerKey;
    /** List of query parameters to append to the settings URL and persisted as part of the JSON representation.
     * @note Sensitive information like user credentials should be provided in [[unsavedQueryParams]] to ensure it is never persisted.
     * @beta
    */
    savedQueryParams?: {
        [key: string]: string;
    };
    /** List of query parameters that will get appended to the settings URL that should *not* be be persisted part of the JSON representation.
     * @beta
    */
    unsavedQueryParams?: {
        [key: string]: string;
    };
    /** Properties specific to the map layer provider.
     * @beta
    */
    readonly properties?: MapLayerProviderProperties;
    readonly subLayers: MapSubLayerSettings[];
    get source(): string;
    /** @internal */
    protected constructor(props: ImageMapLayerProps);
    static fromJSON(props: ImageMapLayerProps): ImageMapLayerSettings;
    /** return JSON representation of this MapLayerSettings object */
    toJSON(): ImageMapLayerProps;
    /** Create a copy of this MapLayerSettings, optionally modifying some of its properties.
     * @param changedProps JSON representation of the properties to change.
     * @returns A MapLayerSettings with all of its properties set to match those of `this`, except those explicitly defined in `changedProps`.
     */
    clone(changedProps: Partial<ImageMapLayerProps>): ImageMapLayerSettings;
    /** @internal */
    protected cloneProps(changedProps: Partial<ImageMapLayerProps>): ImageMapLayerProps;
    /** @internal */
    displayMatches(other: MapLayerSettings): boolean;
    /** Return a sublayer matching id -- or undefined if not found */
    subLayerById(id?: SubLayerId): MapSubLayerSettings | undefined;
    private hasInvisibleAncestors;
    /** Return true if sublayer is visible -- testing ancestors for visibility if they exist. */
    isSubLayerVisible(subLayer: MapSubLayerSettings): boolean;
    /** Return true if all sublayers are invisible. */
    get allSubLayersInvisible(): boolean;
    /** Return the children for a sublayer */
    getSubLayerChildren(subLayer: MapSubLayerSettings): MapSubLayerSettings[] | undefined;
    /** @internal */
    protected static mapTypeName(type: BackgroundMapType): "Aerial Imagery" | "Aerial Imagery with labels" | "Streets";
    setCredentials(userName?: string, password?: string): void;
    /** Collect all query parameters
   * @beta
   */
    collectQueryParams(): {
        [key: string]: string;
    };
}
/** Normalized representation of a [[ModelMapLayerProps]] for which values have been validated and default values have been applied where explicit values not defined.
 * Model map layers are produced from models, typically from two dimensional geometry that may originate in a GIS system.
 * One or more map layers may be included within [[MapImagerySettings]] object.
 * @see [[MapImagerySettings]]
 * @see [[ImageMapLayerSettings]] for image based map layer settings.
 * @public
 */
export declare class ModelMapLayerSettings extends MapLayerSettings {
    /** Specifies the target onto which to drape this model map layer. Defaults to [ModelMapLayerDrapeTarget.Globe]($common).
     * @beta
     */
    readonly drapeTarget: ModelMapLayerDrapeTarget;
    readonly modelId: Id64String;
    get source(): string;
    /** @internal */
    protected constructor(modelId: Id64String, name: string, visible?: boolean, transparency?: number, transparentBackground?: boolean, drapeTarget?: ModelMapLayerDrapeTarget);
    /** Construct from JSON, performing validation and applying default values for undefined fields. */
    static fromJSON(json: ModelMapLayerProps): ModelMapLayerSettings;
    /** return JSON representation of this MapLayerSettings object */
    toJSON(): ModelMapLayerProps;
    /** Create a copy of this MapLayerSettings, optionally modifying some of its properties.
     * @param changedProps JSON representation of the properties to change.
     * @returns A MapLayerSettings with all of its properties set to match those of `this`, except those explicitly defined in `changedProps`.
     */
    clone(changedProps: Partial<ModelMapLayerProps>): ModelMapLayerSettings;
    /** @internal */
    protected cloneProps(changedProps: Partial<ModelMapLayerProps>): ModelMapLayerProps;
    /** @internal */
    displayMatches(other: MapLayerSettings): boolean;
    /** Return true if all sublayers are invisible (always false as model layers do not include sublayers). */
    get allSubLayersInvisible(): boolean;
}
/** JSON representation of a [[BaseMapLayerSettings]].
 * @public
 */
export interface BaseMapLayerProps extends ImageMapLayerProps {
    provider?: BackgroundMapProviderProps;
}
/** A [[ImageMapLayerSettings]] that can serve as the base layer for a [[MapImagerySettings]].
 * The base layer supports all of the same options as any other layer, but also allows for simplified configuration based
 * on a small set of known supported [[BackgroundMapProvider]]s like [Bing Maps](https://www.microsoft.com/en-us/maps).
 * If the base layer was configured from such a provider, that information will be preserved and can be queried; this allows
 * the imagery provider and/or type to be easily modified.
 * @see [[MapImagerySettings.backgroundBase]].
 * @public
 */
export declare class BaseMapLayerSettings extends ImageMapLayerSettings {
    private _provider?;
    /** The provider from which this base layer was configured, if any. */
    get provider(): BackgroundMapProvider | undefined;
    /** Create a base layer from its JSON representation.
     * TODO: This, MapLayerSettings.fromJSON, and MapSubLayerSettings.fromJSON should never return undefined.
     * That means they should not accept undefined for props and should define props such that it fully describes the
     * layer - e.g., url and name must be defined.
     */
    static fromJSON(props: BaseMapLayerProps): BaseMapLayerSettings;
    /** Convert this layer to its JSON representation. */
    toJSON(): BaseMapLayerProps;
    /** @internal */
    cloneProps(changedProps: Partial<BaseMapLayerProps>): BaseMapLayerProps;
    /** Create a copy of this layer. */
    clone(changedProps: Partial<BaseMapLayerProps>): BaseMapLayerSettings;
    /** Create a base layer from a BackgroundMapProvider. */
    static fromProvider(provider: BackgroundMapProvider, options?: {
        invisible?: boolean;
        transparency?: number;
    }): BaseMapLayerSettings;
    /** @internal */
    static fromBackgroundMapProps(props: DeprecatedBackgroundMapProps): BaseMapLayerSettings;
    /** @alpha */
    cloneWithProvider(provider: BackgroundMapProvider): BaseMapLayerSettings;
}
//# sourceMappingURL=MapLayerSettings.d.ts.map