### Installation and Basic Usage Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Instructions on how to install the library using npm and integrate it with MapGL JS API using the `createTerraDrawWithUI` helper function. Includes CSS import and basic MapGL setup. ```APIDOC ## Installation Install the library using npm: ```bash npm install @2gis/mapgl-terra-draw ``` ## Basic Usage with UI Helper Use the `createTerraDrawWithUI` helper function for a quick setup. Remember to include the necessary CSS. ### Method ```ts import { load } from '@2gis/mapgl'; import { createTerraDrawWithUI } from '@2gis/mapgl-terra-draw'; import '@2gis/mapgl-terra-draw/dist/mapgl-terra-draw.css'; load().then((mapgl) => { const map = new mapgl.Map('map', { center: [55.31878, 25.23584], zoom: 13, key: 'Your MapGL JS API key', enableTrackResize: true, }); map.on('styleload', () => { createTerraDrawWithUI({ map, mapgl: mapgl as any, controls: ['color', 'select', 'point', 'polygon', 'circle', 'download', 'clear'], }); }); }); ``` ### Usage via CDN Alternatively, use the CDN links directly in your HTML. ```html

``` ``` -------------------------------- ### Install MapGL TerraDraw Adapter Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Command to install the package via npm. ```bash npm install @2gis/mapgl-terra-draw ``` -------------------------------- ### Integrate MapGL TerraDraw via CDN Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Example of including the library directly in an HTML file using unpkg CDN links. This approach is suitable for simple projects without a build step. ```html

``` -------------------------------- ### Initialize Default Drawing Modes Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt Configures the Terra Draw instance with standard modes like point, polygon, and circle, providing a quick-start setup for map interactions. ```typescript import { TerraDraw } from 'terra-draw'; import { TerraDrawMapGlAdapter, createDefaultModes } from '@2gis/mapgl-terra-draw'; const adapter = new TerraDrawMapGlAdapter({ map, mapgl, coordinatePrecision: 9, }); const draw = new TerraDraw({ adapter, modes: createDefaultModes(), }); draw.start(); draw.setMode('polygon'); ``` -------------------------------- ### Get Raw GeoJSON Snapshot Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Retrieves the raw GeoJSON shapes from the Terra Draw instance without additional styling metadata. ```typescript const { draw } = createTerraDrawWithUI({ ... }); ... draw.getSnapshot(); ``` -------------------------------- ### Integrate via CDN Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt Demonstrates how to include the library via unpkg CDN and initialize the drawing interface within an HTML file. ```html ``` -------------------------------- ### Build and Publish Project Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Commands to compile the project and publish the package to the npm registry. ```bash npm run build npm publish --access=public ``` -------------------------------- ### Initialize MapGL TerraDraw with UI Helper Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Demonstrates how to initialize the drawing tool using the provided UI helper. It requires importing the necessary CSS and calling the createTerraDrawWithUI function after the map style has loaded. ```typescript import { load } from '@2gis/mapgl'; import { createTerraDrawWithUI } from '@2gis/mapgl-terra-draw'; import '@2gis/mapgl-terra-draw/dist/mapgl-terra-draw.css'; load().then((mapgl) => { const map = new mapgl.Map('map', { center: [55.31878, 25.23584], zoom: 13, key: 'Your MapGL JS API key', enableTrackResize: true, }); map.on('styleload', () => { createTerraDrawWithUI({ map, mapgl: mapgl as any, controls: ['color', 'select', 'point', 'polygon', 'circle', 'download', 'clear'], }); }); }); ``` -------------------------------- ### Initialize TerraDraw with MapGL Adapter Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt This snippet demonstrates how to instantiate the TerraDrawMapGlAdapter and integrate it with a MapGL instance. It includes configuration for drawing modes such as select, point, line, polygon, circle, and rectangle, along with basic event listeners for UI controls. ```typescript import { load } from '@2gis/mapgl'; import { TerraDraw, TerraDrawPointMode, TerraDrawPolygonMode, TerraDrawLineStringMode, TerraDrawSelectMode, TerraDrawCircleMode, TerraDrawRectangleMode, ValidateNotSelfIntersecting, } from 'terra-draw'; import { TerraDrawMapGlAdapter } from '@2gis/mapgl-terra-draw'; load().then((mapgl) => { const map = new mapgl.Map('map', { center: [55.31878, 25.23584], zoom: 13, key: 'Your MapGL JS API key', enableTrackResize: true, }); map.on('styleload', () => { const adapter = new TerraDrawMapGlAdapter({ map, mapgl, coordinatePrecision: 9, style: { fillColor: '#ff000033', outlineColor: '#ff0000', outlineWidth: 2, pointCap: 'round', }, }); const draw = new TerraDraw({ adapter, modes: [ new TerraDrawSelectMode({ projection: 'web-mercator', flags: { polygon: { feature: { draggable: true, rotateable: true, scaleable: true, coordinates: { snappable: true, midpoints: true, draggable: true, deletable: true, }, }, }, point: { feature: { draggable: true }, }, linestring: { feature: { draggable: true, rotateable: true, coordinates: { midpoints: true, draggable: true, deletable: true, }, }, }, }, }), new TerraDrawPointMode({ editable: true }), new TerraDrawLineStringMode({ snapping: { toCoordinate: true }, editable: true, }), new TerraDrawPolygonMode({ pointerDistance: 20, editable: true, validation: (feature, { updateType }) => { if (updateType === 'finish' || updateType === 'commit') { return ValidateNotSelfIntersecting(feature); } return { valid: true }; }, }), new TerraDrawCircleMode(), new TerraDrawRectangleMode(), ], }); draw.start(); draw.setMode('polygon'); document.getElementById('select-btn')?.addEventListener('click', () => { draw.setMode('select'); }); document.getElementById('polygon-btn')?.addEventListener('click', () => { draw.setMode('polygon'); }); document.getElementById('clear-btn')?.addEventListener('click', () => { draw.clear(); }); }); }); ``` -------------------------------- ### Advanced Usage with Custom Adapter Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Demonstrates how to use the `TerraDrawMapGlAdapter` class directly for more control over drawing modes, selection behavior, and UI customization. ```APIDOC ## Advanced Usage with `TerraDrawMapGlAdapter` For advanced scenarios, you can instantiate `TerraDrawMapGlAdapter` directly to gain more flexibility. ### Method ```ts import { load } from '@2gis/mapgl'; import { TerraDraw, TerraDrawPointMode, TerraDrawPolygonMode, TerraDrawSelectMode, } from 'terra-draw'; import { TerraDrawMapGlAdapter } from '@2gis/mapgl-terra-draw'; load().then((mapgl) => { const map = new mapgl.Map('map', { center: [55.31878, 25.23584], zoom: 13, key: 'Your MapGL JS API key', enableTrackResize: true, }); map.on('styleload', () => { const draw = new TerraDraw({ adapter: new TerraDrawMapGlAdapter({ map, mapgl, coordinatePrecision: 9, }), modes: [ new TerraDrawSelectMode(), new TerraDrawPointMode(), new TerraDrawPolygonMode(), ], }); const buttons = document.createElement('div'); buttons.style.display = 'flex'; buttons.style.flexDirection = 'column'; buttons.style.gap = '8px'; new mapgl.Control(map, buttons, { position: 'centerLeft' }); const selectButton = document.createElement('button'); selectButton.innerText = 'select'; selectButton.addEventListener('click', () => { draw.setMode('select'); }); buttons.appendChild(selectButton); const pointButton = document.createElement('button'); pointButton.innerText = 'point'; pointButton.addEventListener('click', () => { draw.setMode('point'); }); buttons.appendChild(pointButton); const polygonButton = document.createElement('button'); polygonButton.innerText = 'polygon'; polygonButton.addEventListener('click', () => { draw.setMode('polygon'); }); buttons.appendChild(polygonButton); const clearButton = document.createElement('button'); clearButton.innerText = 'clear'; clearButton.addEventListener('click', () => { draw.clear(); }); buttons.appendChild(clearButton); draw.start(); }); }); ``` ``` -------------------------------- ### Initialize Drawing Interface with createTerraDrawWithUI Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt This snippet demonstrates how to initialize the MapGL map and attach the TerraDraw UI helper. It configures available drawing tools, sets initial styles, and shows how to listen to drawing events and retrieve GeoJSON snapshots. ```typescript import { load } from '@2gis/mapgl'; import { createTerraDrawWithUI } from '@2gis/mapgl-terra-draw'; import '@2gis/mapgl-terra-draw/dist/mapgl-terra-draw.css'; load().then((mapgl) => { const map = new mapgl.Map('map', { center: [55.31878, 25.23584], zoom: 13, key: 'Your MapGL JS API key', enableTrackResize: true, }); map.on('styleload', () => { const { draw, cleanup } = createTerraDrawWithUI({ map, mapgl: mapgl as any, controls: [ 'select', 'point', 'linestring', 'polygon', 'freehand', 'circle', 'angled-rectangle', 'color', 'stroke-width', 'point-cap', 'download', 'clear', ], style: { fillColor: '#3388ff33', outlineColor: '#3388ff', outlineWidth: 3, pointCap: 'round', }, stopByDoubleClick: true, }); draw.setMode('polygon'); const features = draw.getSnapshot(); console.log(features); draw.on('finish', (id, context) => { console.log(`Finished drawing ${context.mode} with id: ${id}`); }); draw.on('select', (id) => { console.log(`Selected feature: ${id}`); }); }); }); ``` -------------------------------- ### Process and Export Features with Styling Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt Demonstrates how to extract drawn features from the adapter, generate styling metadata, and apply these styles to a MapGL instance for rendering. ```typescript import { TerraDrawMapGlAdapter, createTerraDrawWithUI } from '@2gis/mapgl-terra-draw'; const adapter = new TerraDrawMapGlAdapter({ map, mapgl, coordinatePrecision: 9, }); const { draw } = createTerraDrawWithUI({ adapter, map, mapgl, controls: ['select', 'point', 'polygon', 'circle', 'download'], }); function exportFeaturesWithStyling() { const features = draw.getSnapshot(); const { icons, layers } = adapter.addStyling(features); const featureCollection = { type: 'FeatureCollection', icons, layers, features, }; return featureCollection; } function displayExportedData(map, mapgl, featureCollection) { for (const iconName in featureCollection.icons) { map.addIcon(iconName, { url: featureCollection.icons[iconName] }); } for (const layer of featureCollection.layers) { map.addLayer(layer); } const source = new mapgl.GeoJsonSource(map, { data: featureCollection, attributes: { name: 'terra-draw-output', }, }); } ``` -------------------------------- ### Configure Full-Screen Map Container CSS Source: https://github.com/2gis/mapgl-terra-draw/blob/main/demo/index.html Sets the body and html margins to zero and forces the map container to take up 100% of the viewport width and height. This prevents scrollbars and ensures the map fills the entire screen. ```css html, body { margin: 0; padding: 0; } #map { position: absolute; width: 100vw; height: 100vh; overflow: hidden; } ``` -------------------------------- ### Include Material Icons Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Adds the required Material Symbols font link to the HTML head to ensure UI icons render correctly. ```html ``` -------------------------------- ### createTerraDrawWithUI Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt Initializes the drawing interface with built-in controls and styling options on a MapGL map instance. ```APIDOC ## Function: createTerraDrawWithUI ### Description Initializes a fully-featured drawing interface on a MapGL map. This function handles the setup of drawing tools, UI controls, and event listeners for shape manipulation. ### Parameters - **map** (MapGL.Map) - Required - The initialized MapGL map instance. - **mapgl** (Object) - Required - The loaded MapGL JS API object. - **controls** (Array) - Optional - List of enabled tools (e.g., 'select', 'point', 'polygon', 'color', 'download'). - **style** (Object) - Optional - Configuration for shape appearance (fillColor, outlineColor, outlineWidth, pointCap). - **stopByDoubleClick** (boolean) - Optional - If true, stops the drawing mode on double-click. ### Returns - **draw** (TerraDraw) - The underlying TerraDraw instance for programmatic control. - **cleanup** (Function) - A function to remove the drawing interface and event listeners. ### Usage Example ```typescript const { draw, cleanup } = createTerraDrawWithUI({ map, mapgl, controls: ['select', 'polygon', 'color'], style: { fillColor: '#3388ff33', outlineColor: '#3388ff' } }); // Programmatically set mode draw.setMode('polygon'); // Get GeoJSON snapshot const features = draw.getSnapshot(); ``` ``` -------------------------------- ### Render Drawing Data on MapGL Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Iterates through the extracted icons and layers to add them to the MapGL instance and creates a GeoJsonSource for the map features. ```javascript for (const icon in featureCollection.icons) { map.addIcon(icon, { url: featureCollection.icons[icon] }); } for (const layer of featureCollection.layers) { map.addLayer(layer); } const source = new mapgl.GeoJsonSource(map, { data: featureCollection, attributes: { name: 'terra-draw-output', }, }); ``` -------------------------------- ### Advanced Usage with TerraDrawMapGlAdapter Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Shows how to use the TerraDrawMapGlAdapter class directly for full control over drawing modes and custom UI implementation. ```typescript import { load } from '@2gis/mapgl'; import { TerraDraw, TerraDrawPointMode, TerraDrawPolygonMode, TerraDrawSelectMode } from 'terra-draw'; import { TerraDrawMapGlAdapter } from '@2gis/mapgl-terra-draw'; load().then((mapgl) => { const map = new mapgl.Map('map', { center: [55.31878, 25.23584], zoom: 13, key: 'Your MapGL JS API key', enableTrackResize: true, }); map.on('styleload', () => { const draw = new TerraDraw({ adapter: new TerraDrawMapGlAdapter({ map, mapgl, coordinatePrecision: 9, }), modes: [ new TerraDrawSelectMode(), new TerraDrawPointMode(), new TerraDrawPolygonMode(), ], }); const buttons = document.createElement('div'); buttons.style.display = 'flex'; buttons.style.flexDirection = 'column'; buttons.style.gap = '8px'; new mapgl.Control(map, buttons, { position: 'centerLeft' }); const selectButton = document.createElement('button'); selectButton.innerText = 'select'; selectButton.addEventListener('click', () => { draw.setMode('select'); }); buttons.appendChild(selectButton); const pointButton = document.createElement('button'); pointButton.innerText = 'point'; pointButton.addEventListener('click', () => { draw.setMode('point'); }); buttons.appendChild(pointButton); const polygonButton = document.createElement('button'); polygonButton.innerText = 'polygon'; polygonButton.addEventListener('click', () => { draw.setMode('polygon'); }); buttons.appendChild(polygonButton); const clearButton = document.createElement('button'); clearButton.innerText = 'clear'; clearButton.addEventListener('click', () => { draw.clear(); }); buttons.appendChild(clearButton); draw.start(); }); }); ``` -------------------------------- ### Retrieve and Style Drawing Data Source: https://github.com/2gis/mapgl-terra-draw/blob/main/README.md Extracts drawing data as a GeoJSON FeatureCollection and injects custom icons and layers for MapGL rendering. This process ensures that styling metadata is correctly associated with the drawn features. ```javascript const adapter = new TerraDrawMapGlAdapter({ ... }); const { draw } = createTerraDrawWithUI({ adapter, ... }); const features = draw.getSnapshot(); const { icons, layers } = adapter.addStyling(features); const featureCollection = { type: 'FeatureCollection', icons, layers, features, }; ``` -------------------------------- ### Configure Drawing Styles Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt Defines custom visual properties for drawn features such as fill color, outline color, and stroke width using the Style interface. ```typescript import { Style, defaultStyle } from '@2gis/mapgl-terra-draw'; const myStyle: Style = { fillColor: '#3388ff33', outlineColor: '#3388ff', outlineWidth: 3, pointCap: 'round', }; createTerraDrawWithUI({ map, mapgl, style: myStyle, controls: ['select', 'point', 'polygon'], }); ``` -------------------------------- ### Update Drawing Styles Dynamically Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt Shows how to modify the visual properties of the drawing adapter, such as colors and stroke widths, which affects future drawn features. ```typescript import { TerraDrawMapGlAdapter } from '@2gis/mapgl-terra-draw'; const adapter = new TerraDrawMapGlAdapter({ map, mapgl, style: { fillColor: '#3388ff33', outlineColor: '#3388ff', outlineWidth: 3, pointCap: 'round', }, }); adapter.updateStyle({ outlineColor: '#ff0000', fillColor: '#ff000033', }); adapter.updateStyle({ outlineWidth: 5, }); adapter.updateStyle({ pointCap: 'square', }); ``` -------------------------------- ### Convert Hex Colors to Transparent Source: https://context7.com/2gis/mapgl-terra-draw/llms.txt A utility function to append an alpha channel to hex color strings, useful for generating fill colors from existing outline colors. ```typescript import { makeTransparent, defaultStyle } from '@2gis/mapgl-terra-draw'; const transparentBlue = makeTransparent('#3388ff'); const semiTransparent = makeTransparent('#ff0000', '80'); const transparentShort = makeTransparent('#f00'); adapter.updateStyle({ outlineColor: '#00ff00', fillColor: makeTransparent('#00ff00'), }); ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.