@arcgis/core/symbols/support/cimSymbolUtils.d.ts

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

/**
 * Provides utility functions for [CIMSymbols](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/).
 * These methods will allow you to get and set the size, color, and rotation of a CIMsymbol.
 *
 * @since 4.16
 * @see [CIMSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/)
 * @see [symbolService](https://developers.arcgis.com/javascript/latest/references/core/rest/symbolService/)
 * @see [Sample - CIMSymbol lines and polygons](https://developers.arcgis.com/javascript/latest/sample-code/cim-lines-and-polygons/)
 * @see [Sample - Adjust marker placement in polygon symbols](https://developers.arcgis.com/javascript/latest/sample-code/cim-marker-placement/)
 */
import type Color from "../../Color.js";
import type CIMSymbol from "../CIMSymbol.js";

export interface ScaleCIMSymbolOptions {
  /**
   * When `true`, this property will preserve the outline
   *        width of the symbol. This property will only work when [`scaleSymbolsProportionally`](https://github.com/Esri/cim-spec/blob/master/docs/v2/CIMSymbols.md#cimvectormarker-1)
   *        is `false` on the symbol layer. If `scaleSymbolsProportionally` is `true`, this property will be ignored.
   */
  preserveOutlineWidth: boolean;
}

export interface ApplyCIMSymbolColorOptions {
  /**
   * The symbol layers to apply the color to.
   *    This only applies to CIMPolygonSymbols and CIMPointSymbols with embedded polygon marker graphics.
   *    The `"fill"` option will only apply the color to the fill symbol layers - CIMSolidFill, CIMHatchFill, CIMPictureFill, etc.
   *    The `"outline"` option will only apply the color to the stroke symbol layers - like CIMSolidStroke and CIMPictureStroke.
   *    The `"fill-and-outline"` option will apply the color to both fill and stroke layers. The default value is `"fill"`.
   */
  layersToColor: "fill" | "outline" | "fill-and-outline";
}

/**
 * Returns the size of a given CIMSymbol. The size of a CIMSymbol is defined as the size of the largest symbol layer.
 *
 * @param symbol - The CIMSymbol from which to get the size.
 * @returns Returns the size of the symbol in pixels.
 */
export function getCIMSymbolSize(symbol: CIMSymbol): number;

/**
 * Scales the largest layer of a CIMSymbol to a given size. The other symbol layers will scale accordingly.
 *
 * @param symbol - The CIMSymbol to scale.
 * @param size - The desired size for the symbol.
 * @param options - Options for scaling the symbol.
 */
export function scaleCIMSymbolTo(symbol: CIMSymbol | null | undefined, size: number, options?: ScaleCIMSymbolOptions): void;

/**
 * Returns the first color of the symbol layers in a CIMSymbol.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > - Not supported on CIMGradientStroke and CIMGradientFill symbol layers.
 *
 * @param symbol - The CIMSymbol from which to get the color.
 * @returns Returns the color of the CIMSymbol.
 */
export function getCIMSymbolColor(symbol: CIMSymbol): Color | null | undefined;

/**
 * Sets the color of the symbol layers of a CIMSymbol to a given value if the symbol layer is not color locked.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > - Not supported on CIMGradientStroke and CIMGradientFill symbol layers.
 *
 * @param symbol - The CIMSymbol to set the color on.
 * @param color - The desired color value for the symbol.
 * @param options - _Since 4.23_ The options for setting the color of the CIMSymbol.
 */
export function applyCIMSymbolColor(symbol: CIMSymbol, color: Color, options?: ApplyCIMSymbolColorOptions): void;

/**
 * Returns the rotation value of a CIMSymbol.
 *
 * @param symbol - The CIMSymbol from which to get the rotation.
 * @param clockwise - Indicates whether to get the rotation value as clockwise rotation. Default is `false`.
 * @returns The rotation value of the symbol in degrees.
 */
export function getCIMSymbolRotation(symbol: CIMSymbol, clockwise?: boolean): number;

/**
 * Sets the rotation value of a CIMSymbol.
 *
 * @param symbol - The CIMSymbol to set the rotation on.
 * @param rotation - The desired rotation of the symbol in degrees.
 * @param clockwise - Indicates whether to rotate the symbol clockwise. Default is `false`.
 */
export function applyCIMSymbolRotation(symbol: CIMSymbol, rotation: number, clockwise?: boolean): void;