UNPKG

@vertigis/viewer-spec

Version:

VertiGIS Viewer Specification

942 lines (941 loc) 29.7 kB
import type Viewpoint from "@arcgis/core/Viewpoint"; import type Extent from "@arcgis/core/geometry/Extent"; import type Point from "@arcgis/core/geometry/Point.js"; import type SpatialReference from "@arcgis/core/geometry/SpatialReference"; import type { BasemapJson } from "@vertigis/arcgis-extensions/json/BasemapJson.js"; import type { OperationalLayerJson } from "@vertigis/arcgis-extensions/json/OperationalLayerJson.js"; import type { PortalItemLike } from "@vertigis/arcgis-extensions/utilities/portal"; import type { Command } from "../Command.js"; import { CommandRegistry } from "../CommandRegistry.js"; import type { Event } from "../Event.js"; import { EventRegistry } from "../EventRegistry.js"; import type { MapsLike } from "../common.js"; /** * A set of parameters used to run a job. */ export interface JobParameters { [properties: string]: unknown; } /** * Available print output formats (printing gen2). */ export declare const printOutputFormats: readonly ["AIX", "BMP", "EMF", "EPS", "GIF", "JPG", "PDF", "PNG", "PNG32", "SVG", "SVGZ", "TGA", "TIFF"]; /** * Represents the print output format type (printing gen2). Note: Output format * is ignored and PDF is used automatically if more than one page is exported. */ export type PrintOutputFormat = (typeof printOutputFormats)[number]; /** * Represents a print spatial reference. */ export interface PrintSpatialReference { /** * WKID. */ wkid?: number; /** * Latest WKID. */ latestWkid?: number; /** * WKT String. */ wkt?: string; } /** * Represents the print extent. */ export interface PrintExtent { /** * Xmin value. */ xmin: number; /** * Ymin value. */ ymin: number; /** * Xmax value. */ xmax: number; /** * Ymax value. */ ymax: number; /** * Center point. */ center?: Point; /** * Spatial reference. */ spatialReference: PrintSpatialReference; } /** * Represents the map options. */ export interface MapOptions { /** * Defines the extent of the map to be printed. The spatial reference of the * extent object is optional; when it is not provided, it is assumed to be * in the map's spatial reference. When the aspect ratio of the map extent * is different than the size of the map on the output page or the * ExportWebMap:ExportOptions:outputSize, you might notice more features on * the output map. */ extent: PrintExtent; /** * The map scale at which you want your map to be exported. When scale is * used, it takes precedence over the extent, but the output map is drawn at * the requested scale centered on the center of the extent. */ scale?: number; /** * The spatial reference of the map. The order of preference when * spatialReference is missing is as follows: * * - ExportWebMap:MapOptions.extent.spatialReference * - ExportWebMap:BaseMap.baseMapLayers.spatialReference * - Map template's spatial reference. */ spatialReference?: PrintSpatialReference; /** * This represents the number of degrees by which the map frame will be * rotated, measured counterclockwise from the north. To rotate clockwise, * use a negative value. */ rotation?: number; } /** * Represents the export options. */ export interface ExportOptions { /** * The resolution in dots per inch. The default is 96 dpi. */ dpi?: number; /** * Size of the map in pixels. The size must be defined when an empty string * or MAP_ONLY (without quotation marks) is passed in as a value to the * layout_template parameter. If layout_template is not specified as * MAP_ONLY or an empty string, the map frame with the name WEBMAP_MAP_FRAME * of the referenced DEFAULT layout portal item in layout_template print * parameter takes precedence over outputSize. */ outputSize?: number[]; } /** * Represents the legend options. */ export interface LegendOptions { /** * Specifies if the legend of all operational layers should be added to the * layout. If true, operationalLayers can be undefined. Note: this is no * ESRI standard property and only works with VertiGIS Studio Printing * Engine. */ operationalLayersAutoSet?: boolean; /** * Specifies the operational layers whose legends will be added to the * layout. */ operationalLayers?: { /** * String representing the ID of the layer. The ID must be unique and * must match the layer's ID in the operationalLayers element where the * operational layer is defined. */ id: string; /** * An array of sublayers whose element types are string or number and * contextual to the operational layer type. For example, for a map * service layer, it must be a number; for a WMS layer, it must be a * string. It is recommended that you specify subLayerIds values for * operational layers that have sublayers. Once omitted, in the case of * map service and WMS layers, legends from all sublayers are added to * the legend element on the layout. For feature or graphics layers, the * sublayers property does not need to be set. */ subLayerIds?: string[] | number[]; }[]; } /** * Represents the layout options. */ export interface LayoutOptions { /** * Specifies properties of a legend element on the layout. */ legendOptions?: LegendOptions; /** * Dynamic text elements as array of name-value pairs. Applies for all * layout page types. Sets the values of layout function fields for all * layouts containing the specified functions fields. Values must be * strings. Function fields of type string and additionally of type image * can also be set when using additionalSettings:dynamicElements. Function * field values can be applied individually for specific layout page types * by using: * * - AdditionalSettings:page:dynamicElements. * - AdditionalSettings:pageCover:dynamicElements. * - AdditionalSettings:pageOverview:dynamicElements. * - AdditionalSettings:pageLegend:dynamicElements. */ customTextElements?: unknown; } /** * Represents the export web map as defined by ESRI in * https://enterprise.arcgis.com/en/server/latest/publish-services/windows/exportwebmap-specification.htm. */ export interface ExportWebMap { /** * The object mapOptions is required and defines map display properties. */ mapOptions: MapOptions; /** * This object specifies settings for the output map. */ exportOptions?: ExportOptions; /** * This defines settings for different available page layout elements and is * only needed when an available layout template is chosen. Page layout * elements include well-known VertiGIS Studios function fields and custom * text elements. */ layoutOptions?: LayoutOptions; /** * The operationalLayers list contains all the operational layers to be * displayed in the map. The order of the array defines the order of the * layers in the map. The type of each layer is defined by the URL resource * response. If the resource cannot be determined from the URL, the type * property defines the type. For example, a WMS layer requires that you * specify "type": "wms". There are some properties common to all types of * operational layers, while others are specific to each type of operational * layer. * * In case of secured layers, specify the token in a layer definition. A * user name and password are not supported as part of the URL. */ operationalLayers?: OperationalLayerJson[]; /** * The map contains one baseMap, which has a title, and a baseMapLayers * property that contains an ordered list of baseMapLayers. Each * baseMapLayer must be in the same spatial reference and tiling scheme. * When there is a baseMap, it defines the map's spatial reference. */ baseMap?: BasemapJson; } /** * Represents an additional export web map. */ export interface AdditionalExportWebMap { /** * Name of the additional map frame in the layout. Well-known additional map * frame names are 'OVERVIEW' for the overview map and * 'WEBMAP_MAP_FRAME_PAGE_OVERVIEW' for the overview page map. For a custom * additional web frame name use the map frame name as defined in the * layout. For fetching the available map frames for layouts or layout * packages use the 'Get Layout Template Info Task'. */ name: string; /** * The export web map properties. */ Map_As_JSON: ExportWebMap; } /** * Represents the portal authentication settings. */ export interface PortalAuthentication { /** * Whether the access to an ArcGIS Online / ArcGIS Enterprise organization * is anonymous. If anonymous is true, no token is required. */ anonymous: boolean; /** * URL of an ArcGIS Enterprise or ArcGIS Online organization. If not * defined, ArcGIS Online access is assumed. */ portal_url: string; /** * Access token. Required for non-anonymous access. */ token?: string; /** * Access token referer. Required for non-anonymous access if the token was * created with the ESRI 'Generate Token Service'. */ referer?: string; } /** * Represents the layer objects selection Settings. */ export interface Selection { /** * Layer object IDs. */ oidList: number[]; /** * Web map layer ID. */ layerId: string; /** * Whether the default object selection graphics should be visible for * selected objects. If 'true' or not defined, the ArcGIS default object * selection graphics are used. If 'false', object selection graphics are * expected in the export web map request parameter (e.g. operational layer * with custom renderer for selected objects, or pre-defined selection * geometries with custom renderer in feature collections). */ visible: boolean; } /** * Represents the time interval units. */ export type IntervalUnits = "MILLISECONDS" | "SECONDS" | "MINUTES" | "HOURS" | "DAYS" | "WEEKS" | "MONTHS" | "YEARS" | "DECADES" | "CENTURIES"; /** * Represents the time series settings. */ export interface TimeSeries { /** * Maximum count of time series PDF documents within the returned ZIP * archive. If not set, no limit for time series PDF document exports is * used. Depending on the client and the execution environment and the * template- / map properties, the clients should always define a suitable * value. */ maxCount?: number; /** * Client time zone information. Default is UTC. */ timeZone?: { /** * Offset in hours to UTC without daylight saving time (DST). */ utcOffset: number; /** * Timezone name. Used for the time function field. */ name: string; }; /** * Human-readable date time pattern in ESRI format: * https://pro.arcgis.com/en/pro-app/latest/help/data/tables/format-numeric-and-date-fields.htm. * Used for the time function field. Default is 'yyyy-MM-dd hh:mm:ss'. */ datetimePattern?: string; /** * Export interval in milliseconds or in other interval units if defined. * Requires a single export time in the array with a time range > 0. If * defined, an export is triggered for each interval starting at the time * range <startTime> and stopping at <endTime>. If no main map with one or * more visible time-aware operational layers is available for exporting, or * if the defined interval does not fit into the specified time range, this * property is ignored. */ interval?: number; /** * Export interval units. Requires a defined interval. Default is * MILLISECONDS. */ intervalUnits?: IntervalUnits; /** * Export Times. Triggers an export for each defined export time. Export * time in milliseconds UTC. Requires at least one entry. */ times: number[][]; } /** * Represents the range settings. */ export interface Range { /** * Start value. */ start: number; /** * End value. */ end: number; /** * Whether the start value is included in the value range. */ includeStart: boolean; /** * Whether the end value is included in the value range. */ includeEnd: boolean; } /** * Represents the range series settings. */ export interface RangeSeries { /** * Maximum count of value range series pages per PDF document. If not set, * no limit for value range series PDF page exports is used. Depending on * the client and the execution environment and the template- / map * properties, the clients should always define a suitable value. */ maxCount?: number; /** * Export interval in integer or float. Requires a single export value range * in the array with a value range extent > 0. If defined, an export is * triggered for each interval starting at the value range <start> and * stopping at <end>. If no main map with one or more visible z-aware layers * is available for exporting, or if the defined interval does not fit into * the specified value range span, this property is ignored. */ interval?: number; /** * Export value ranges. Triggers an export for each defined export value * range. Requires at least one entry. */ ranges: Range[]; } /** * Represents the table data selection mode. */ export type DataSelectionMode = "All" | "InExtent" | "SelectedAll" | "SelectedInExtent"; /** * Represents the attribute table settings. */ export interface AttributeTable { /** * Name of attribute table. */ name: string; /** * ID of the map layer used as data source. */ layerId: string; /** * Data selection mode. */ mode: DataSelectionMode; /** * List of table fields to show in the table. */ fields: string[]; } /** * Represents the geo transformation in the settings. */ export interface GeoTransformation { /** * WKID. */ wkid: number; /** * Name. */ name: string; } /** * Represents the dynamic element type. */ export type DynamicElementType = "string" | "image"; /** * Represents a dynamic element. A dynamic element can be a custom text element * (type: string) or a custom image element (type: image). */ export interface DynamicElement { /** * Type. */ type: DynamicElementType; /** * Name. */ name: string; /** * Value. */ value: string; } /** * Represents the default page settings. The properties match the index info * page properties as received by the VertiGIS Printing Engine as response of an * 'Get Index Info Task'. */ export interface Page { /** * Page scale. */ scale: number; /** * Page rotation. */ rotation?: number; /** * Page centerpoint x-coordinate. */ centerX?: number; /** * Page centerpoint y-coordinate. */ centerY?: number; /** * Projected page geometry. An array of geometry points according to the * ESRI specification. */ geometry?: number[][]; /** * Spatial reference of the projected page geometry. */ spatialReference?: PrintSpatialReference; /** * Output spatial reference of the projected page geometry for export. */ spatialReferenceOut?: PrintSpatialReference; /** * Transformation name for projecting the page geometry between the * projected page geometry spatial reference and the output spatial * reference. */ transformationName?: string; /** * Transformation WKT string for projecting the page geometry between the * projected page geometry spatial reference and the output spatial * reference. */ transformationString?: string; /** * Dynamic elements of the default page additionally to the dynamic text * elements in exportWebMap:layoutOptions:customTextElement and the dynamic * elements in additionalSettings. These elements take precedence over the * elements in exportWebMap:layoutOptions:customTextElement and the elements * in addtional Settings root, if they have the same type and name. */ dynamicElements?: DynamicElement[]; /** * Layer objects selections of the default Page additionally to the Layer * objects selections in additionalSettings. */ selection?: Selection; } /** * Represents the seamless page settings. */ export interface PageSeamless { /** * Page scale. */ scale: number; /** * Index line or polygon geometry. An array of geometry points according to * the ESRI array specification. Excepted geometries are a polyline with * CENTER LEFT and CENTER RIGHT coordinates or a rectangle with BOTTOM LEFT, * TOP LEFT, TOP RIGHT, BOTTOM RIGHT coordinates or a complex polygon with * arbitrary vertices. A polyline geometry defines the delta, the current * template's mapframe width should be updated with. A rectangle or complex * polygon geometry defines an arbitrary extent, for the current template's * mapframe. For complex polygons the extent is defined by the polygon's * bounding box. For complex polygons geometry rotation can not be * considered. */ geometry?: number[][]; /** * Spatial reference. */ spatialReference: PrintSpatialReference; } /** * Represents the cover page settings. */ export interface PageCover { /** * Whether the cover page is visible. */ visible?: boolean; /** * Dynamic elements of the cover page additionally to the dynamic text * elements in exportWebMap:layoutOptions:customTextElement and the dynamic * elements in additionalSettings. These elements take precedence over the * elements in exportWebMap:layoutOptions:customTextElement and the elements * in addtional settings root, if they have the same type and name. */ dynamicElements?: DynamicElement[]; } /** * Represents the overview page settings. */ export interface PageOverview { /** * Whether the overview page is visible. */ visible?: boolean; /** * Dynamic elements of the overview page additionally to the dynamic text * elements in exportWebMap:layoutOptions:customTextElement and the dynamic * elements in additionalSettings. These elements take precedence over the * elements in exportWebMap:layoutOptions:customTextElement and the elements * in addtional settings root, if they have the same type and name. */ dynamicElements?: DynamicElement[]; /** * Page graphics settings. */ pageGraphics?: { /** * Whether the page graphics are visible. */ visible?: boolean; /** * Page stroke RGB color according to the ESRI RGB color specification. */ colorStroke: number[]; /** * Page fill RGB color according to the ESRI RGB color specification. */ colorFill: number[]; }; /** * Page overlap graphics settings. */ pageGraphicsOverlap?: { /** * Whether the page overlap fill graphics are visible. */ visibleFill?: boolean; /** * Page overlap fill RGB Color according to the ESRI RGB color * specification. */ colorFill?: number[]; }; /** * Page graphics index settings. */ pageGraphicsIndex?: { /** * Whether the index line graphics is visible. */ visibleStroke?: boolean; /** * Whether the page number annotations are visible. */ visibleAnnotation?: boolean; /** * Index line stroke RGB color according to the ESRI RGB color * specification. */ colorStroke?: number[]; /** * Page number annotations RGB color according to the ESRI RGB color * specification. */ colorAnnotation?: number[]; }; } /** * Represents the legend page settings. */ export interface PageLegend { /** * Whether the legend page is visible. */ visible?: boolean; /** * Dynamic elements of the legend page additionally to the dynamic text * elements in exportWebMap:layoutOptions:customTextElement and the dynamic * elements in additionalSettings. These elements take precedence over the * elements in exportWebMap:layoutOptions:customTextElement and the elements * in addtional settings root, if they have the same type and name. */ dynamicElements?: DynamicElement[]; /** * Whether the legend items of dynamic layers, organized in composite layers * on root level, should be exported in seperate legend pages. Legend items * are seperated if this value is set to 'true'. This might result in * additional legend page exports. */ layerCompositeExport?: boolean; /** * Whether the legend items of visible layers should only be exported if * related features are visible in the print extent. If not defined, the * value from the layout's default legend item (ArcGIS Pro: 'Only show * feature visible in the map extent') is used. */ itemsAutoVisibility?: boolean; } /** * Represents the additional settings. */ export interface AdditionalSettings { /** * Authentication for layout or layout package portal item access. */ authentication?: PortalAuthentication; /** * Security settings. */ security?: { /** * AES-128 encrypted password to secure resulting PDF documents. Clients * must use shared AES crypto key for password encryption. */ outputPassword: string; }; /** * Default seamless page settings for prints with layout or layout packages. * Mandatory for a seamless page print. */ seamless?: PageSeamless; /** * Default series pages settings for prints with layout or layout packages. * Mandatory for unprojected or projected spatial series pages prints. */ pages?: Page[]; /** * Cover page settings for prints with layout packages. */ pageCover?: PageCover; /** * Overview page settings for prints with layout packages. */ pageOverview?: PageOverview; /** * Legend page settings for prints with layout packages. */ pageLegend?: PageLegend; /** * Layer objects selections. */ selection?: Selection; /** * Series time settings for time-aware layers. */ timeSeries?: TimeSeries; /** * Series range settings for range/z-aware layers. */ rangeSeries?: RangeSeries; /** * Attribute tables settings. */ attributeTables?: AttributeTable[]; /** * Geo transformations for prints with layout or layout packages. Geo * transformations used for maps to avoid spatial displacement between * operational layers and basemap layers if they have incompatible * underlying geographic coordinate systems. These geo transformations are * added to all maps in the request. They are ignored if no geo * transformation is necessary. Also see: * https://developers.arcgis.com/rest/services-reference/enterprise/pdf/gtf_pdf_11.1.pdf. */ geoTransforms?: GeoTransformation[]; /** * Dynamic elements additionally to the dynamic text elements in the * ExportWebMap:LayoutOptions:customTextElement. These elements take * precedence over the elements in * ExportWebMap:LayoutOptions:customTextElement, if they have the same type * and name. */ dynamicElements?: DynamicElement[]; } /** * Prepared print job arguments (printing gen2). */ export interface PreparedPrintJobArgs { /** * Export web map. */ webMap?: ExportWebMap; /** * Additional settings. */ additionalSettings?: AdditionalSettings; /** * Additional export web maps. */ additionalWebMaps?: AdditionalExportWebMap[]; } /** * The arguments required by the printing.run command when printing with * VertiGIS Studio ArcGIS Pro layouts, -layout packages or map only (printing * gen2). */ export interface RunLayoutPrintArgs extends RunPrintArgsBase { /** * The ID of the layout- (e.g.: vglay_xxx) or layout package (e.g.: * vglaypk_xxx) item to print with or "MAP_ONLY" for map only prints. */ layoutId: string; /** * The print output format or PDF as default. */ outputFormat?: PrintOutputFormat; } /** * The arguments required by the printing.run command when printing with * templates (printing gen1). */ export interface RunPrintArgs extends RunPrintArgsBase { /** * The WKID of the spatial reference used to draw a grid on the map(s). */ grid?: SpatialReference; } /** * The base arguments for the printing.run command. */ interface RunPrintArgsBase { /** * The map(s) to print. */ maps: MapsLike; /** * The ID of the report item. */ id?: string; /** * The title of the report. */ title?: string; /** * The portal item where the report is located. */ portalItem?: PortalItemLike; /** * The DPI with which to print. */ dpi?: number; /** * The scale of the map(s). Defaults to the map's current scale. */ scale?: number; /** * The initial extent of the 2D map(s). Defaults to the map's current * extent. If scale is provided, only the center point is used. */ extent?: Extent; /** * The initial viewpoint of the 3D map(s). Defaults to the scene's current * viewpoint. */ viewpoint?: Viewpoint; /** * The rotation of the map(s). Defaults to the map's current rotation. */ rotation?: number; /** * Additional parameters used in the print template, specified as key-value * pairs. */ parameters?: JobParameters; /** * A unique ID used to track a print job. */ instanceId?: string; } /** * Base for the Print Event Args interfaces. */ export interface PrintEventArgsBase { /** * The ID of the print template being used. */ printTemplateId: string; /** * A unique ID to track the running of this print. */ instanceId: string; } /** * Arguments for the printing.print-error event. */ export interface PrintErrorEventArgs extends PrintEventArgsBase { /** * The error message. */ message: string; /** * The HTTP status code associated with the error, if it's a HTTP error. */ errorCode?: number; /** * The URL from which to download the print log created by the engine. */ downloadLogUrl?: string; } /** * Arguments for the printing.print-finished event. */ export interface PrintFinishedEventArgs extends PrintEventArgsBase { /** * The URL from which to download the print. */ downloadUrl: string; /** * The URL from which to download the print log created by the engine. */ downloadLogUrl?: string; } /** * Arguments for the printing.print-progress event. */ export interface PrintProgressEventArgs extends PrintEventArgsBase { } /** * Arguments for the printing.print-preparing event. */ export interface PrintPreparingEventArgs extends PrintEventArgsBase { } /** * Arguments for the printing.print-prepared event. */ export interface PrintPreparedEventArgs extends PrintEventArgsBase { /** * The print job arguments. */ printJobArgs?: PreparedPrintJobArgs; } /** * Arguments for the printing.print-started event. */ export interface PrintStartedEventArgs extends PrintEventArgsBase { /** * The title of the print. */ title?: string; } export declare class PrintCommands extends CommandRegistry { protected readonly _prefix = "printing"; /** * Run a print job with a given map and template/layout. */ get run(): Command<RunPrintArgs | RunLayoutPrintArgs>; } export declare class PrintEvents extends EventRegistry { protected readonly _prefix = "printing"; /** * Raised before a print gets prepared. * * @webOnly */ get printPreparing(): Event<PrintPreparingEventArgs>; /** * Raised when a print was prepared, but not yet started printing. * * @webOnly */ get printPrepared(): Event<PrintPreparedEventArgs>; /** * Raised when a print has started running. */ get printStarted(): Event<PrintStartedEventArgs>; /** * Raised while a print is running to provide updates on its status. */ get printProgress(): Event<PrintProgressEventArgs>; /** * Raised when a print has finished running. Event arguments include the * print download URL. */ get printFinished(): Event<PrintFinishedEventArgs>; /** * Raised when an error occurs with running a print. */ get printError(): Event<PrintErrorEventArgs>; } export {};