@arcgis/core/rest/symbolService.d.ts

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

/**
 * Represents [symbol service](https://developers.arcgis.com/rest/services-reference/enterprise/symbol-server.htm) resources exposed by the ArcGIS REST API. This module provides
 * resources to convert [Scalable Vector Graphics](https://pro.arcgis.com/en/pro-app/latest/help/mapping/layer-properties/scalable-vector-graphics-support.htm) (SVG) to
 * [CIMSymbols](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/).
 *
 * @since 4.25
 * @see [CIMSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/)
 * @see [cimSymbolUtils](https://developers.arcgis.com/javascript/latest/references/core/symbols/support/cimSymbolUtils/)
 */
import type { RequestOptions } from "../request/types.js";
import type { GenerateSymbolParameters, GenerateSymbolResponse } from "./types.js";

/**
 * Converts a [Scalable Vector Graphic](https://pro.arcgis.com/en/pro-app/latest/help/mapping/layer-properties/scalable-vector-graphics-support.htm) (SVG) to a
 * [CIMSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/CIMSymbol/).
 *
 * If using a SVG string value in the [GenerateSymbolParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/types/#GenerateSymbolParameters), the XML namespace (`xmlns`) must be defined.
 * For SVGs defined in `FormData` or an `HTMLFormElement`, the `name` of the element in the form must be `"svgImage"`, as shown in the examples below.
 *
 * The returned CIMSymbol will always be a [CIMPointSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/cim/types/#CIMPointSymbol)
 * with a [CIMVectorMarker](https://developers.arcgis.com/javascript/latest/references/core/symbols/cim/types/#CIMVectorMarker) symbol layer where `size = 10`. To update the size of the symbol, use [scaleCIMSymbolTo()](https://developers.arcgis.com/javascript/latest/references/core/symbols/support/cimSymbolUtils/#scaleCIMSymbolTo).
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a symbol service.
 * @param params - Input parameters for converting an SVG to CIM Symbol.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns A promise that resolves with the response of the generate symbol method that contains the CIM Symbol.
 * @example
 * // Using a string.
 * const svgString = `
 *    <svg xmlns="http://www.w3.org/2000/svg" height="200" width="200">
 *      <path d="M150 0 L75 200 L225 200 Z" />
 *    </svg>
 * `;
 * const params = { svgImage: svgString };
 * symbolService.generateSymbol(symbolServiceUrl, params).then({symbol} => {
 *   // apply the CIMSymbol to a graphic
 *   graphicA.symbol = symbol;
 * });
 * @example
 * // Using FormData.
 * const blob = new Blob([svgSymbol.trim()], { type: "image/svg+xml" });
 * const formData = new FormData();
 * formData.append("svgImage", blob, "symbol.svg");
 *
 * const params = { svgImage: formData };
 * symbolService.generateSymbol(symbolServiceUrl, params).then({symbol} => {
 *   // apply the CIMSymbol to a graphic
 *   graphicB.symbol = symbol;
 * });
 * @example
 * // Using HTMLFormElement.
 * <!-- HTML Element -->
 * <form name="uploadForm">
 *   <input type="file" name="svgImage" id="svgFile" />
 * </form>
 * // JavaScript
 * const uploadForm = document.forms["uploadForm"];
 * uploadForm.addEventListener("change", (event) => {
 *     const fileName = event.target.value.toLowerCase();
 *     if (fileName.includes(".svg")) {
 *         const params = { svgImage: uploadForm };
 *         symbolService.generateSymbol(symbolServiceUrl, params).then({symbol} => {
 *            // apply the CIMSymbol to a graphic
 *            graphicC.symbol = symbol;
 *         });
 *     }
 * });
 */
export function generateSymbol(url: string, params: GenerateSymbolParameters, requestOptions?: RequestOptions): Promise<GenerateSymbolResponse>;