From a72e1715fadb2a4968649ca648dd8c9f926b79d5 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 12:41:18 -0400 Subject: [PATCH 1/9] wip --- docs/README.md | 28 +++--- docs/modules/bing-maps/README.md | 92 ------------------- .../bing-maps/api-reference/deck-overlay.md | 2 +- docs/modules/editable-layers/README.md | 19 +--- docs/modules/react-graph-layers/sidebar.json | 2 +- docs/whats-new.md | 4 +- website/src/docs-sidebar.js | 10 +- 7 files changed, 30 insertions(+), 127 deletions(-) diff --git a/docs/README.md b/docs/README.md index 094862b0..3f378f7c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,24 +1,28 @@ # Community Modules -This repository contains a collection of community supported modules for [deck.gl](https://deck.gl). +This repository contains a collection of community supported modules for [deck.gl](https://deck.gl), that are intended to complement the various modules already provided by the core deck.gl framework. Some modules type are: -The modules in this repository are intended to be used together with deck.gl. +- additional layer packs +- additional base map integrations +- react bindings -Note that these modules are not officially supported by the deck.gl team, but have at least some part-time support from one or more community members. +## Support -## Incubation +Community modules are not officially supported by the deck.gl team, but have at least some intermittent, part-time support from one or more community members. -There is a high bar when adding new code to themain deck.gl repository. The deck.gl-community repository is sometimes used to prepare (incubate) new software components so that they are ready to be added to deck.gl. +Note that the continued inclusion of each module into this repository depends to a large extent on whether there is sufficient community support for the module. Note that modules can be removed from this repository if the core deck.gl team feels that the community is no longer able to provide sufficient support. -When proposing the addition of a new component, such as a new deck.gl layer, -to the core deck.gl maintainers, it is helpful to be able to prepare the component together with tests, documentation and examples outside of the core repository but within a similar code environment. +If a module was to be removed, applications can of course copy the module's source code, but will need to maintain the code on their own. -To be clear, many components in this repository are not intended to be added to the main deck.gl repository. +## Contributing a module -## Longevity +If you have a module that you think could fit into this repository, please start by opening a GitHub issue to start a discussion, or reach out in the OpenJS slack. -The continued inclusion of each module into this repository depends to a large extent on whether there is sufficient community interest in supporting the module. Modules can be removed if the core deck.gl team feels that there is no longer sufficient support. +## Upstreaming to deck.gl? -## Contributing a module +There is a high bar when adding new code to the main deck.gl repository. The deck.gl-community repository is sometimes used to prepare (incubate) new software components so that they are ready to be added to deck.gl. + +Therefore when proposing the addition of a new component, such as a new deck.gl layer, +to the core deck.gl maintainers, it is helpful to be able to prepare the component in a monorepo environment that is similar to the deck.gl repo, complete with tests, documentation and examples. This can avoid a length and frustrating review process in the deck.gl repo. -If you have a module that you think could fit into this repository, open an issue or PR and start a discussion, or reach out in the OpenJS slack. +To be clear, most components in this repository will never be added to the main deck.gl repository. diff --git a/docs/modules/bing-maps/README.md b/docs/modules/bing-maps/README.md index 15d7c7ea..6bc10582 100644 --- a/docs/modules/bing-maps/README.md +++ b/docs/modules/bing-maps/README.md @@ -2,95 +2,3 @@ This module allows [deck.gl](https://deck.gl) to be used as a Bing Maps custom layer. -## Installation - -```bash -npm install deck.gl deck.gl-bing-maps -``` - -## Usage - -```js -import {loadModules} from 'deck.gl-bing-maps'; -import {GeoJsonLayer} from 'deck.gl'; - -loadModules().then(({Maps, Location, DeckOverlay}) => { - // Create map - const map = new Map(document.getElementById('map'), { - credentials: 'YOUR_API_KEY', - // Disable modes that are not supported - disableBirdsEye: true, - disableStreetside: true - }); - - map.setView({ - center: new Location(37.78, -122.45), - zoom: 10 - }); - - // Add deck.gl overlay - const deckOverlay = new DeckOverlay({ - layers: [ - new GeoJsonLayer({ - data: - 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_50m_admin_0_scale_rank.geojson', - lineWidthMinPixels: 2, - getLineColor: [60, 60, 60], - getFillColor: [200, 200, 200] - }) - ] - }); - map.layers.insert(deckOverlay); -}); -``` - -## API Reference - -### loadModules - -`loadModules(moduleNames)` - -Arguments: - -- `moduleNames` (`string[]?`) - Optional modules to load, e.g. `'Microsoft.Maps.GeoJson'`, `'Microsoft.Maps.DrawingTools'` - -Returns a Promise that resolves to the global `Microsoft.Maps` namespace. A custom class, `DeckOverlay`, is also added to the namespace. - -### DeckOverlay - -An implementation of [CustomOverlay](https://docs.microsoft.com/en-us/bingmaps/v8-web-control/map-control-api/customoverlay-class). - -```js -const deckOverlay = new DeckOverlay({...}); -map.layers.insert(deckOverlay); -``` - -The constructor accepts a props object that is passed to the `Deck` constructor. See the [limitations](#supported-features-and-limitations) section below for more details. - -The following `Deck` methods can be called directly from a `DeckOverlay` instance: - -- `deckOverlay.setProps` -- `deckOverlay.pickObject` -- `deckOverlay.pickMultipleObjects` -- `deckOverlay.pickObjects` -- `deckOverlay.redraw` -- `deckOverlay.finalize` - -## Supported Features and Limitations - -Supported deck.gl features: - -- Layers -- Effects -- Auto-highlighting -- Attribute transitions -- `onHover` and `onClick` callbacks -- Tooltip - -Not supported features: - -- Tilting -- Multiple views -- Controller -- React integration -- Gesture event callbacks (e.g. `onDrag*`) diff --git a/docs/modules/bing-maps/api-reference/deck-overlay.md b/docs/modules/bing-maps/api-reference/deck-overlay.md index a4bc7119..b4333276 100644 --- a/docs/modules/bing-maps/api-reference/deck-overlay.md +++ b/docs/modules/bing-maps/api-reference/deck-overlay.md @@ -1,4 +1,4 @@ -## API Reference +# DeckOverlay ### loadModules diff --git a/docs/modules/editable-layers/README.md b/docs/modules/editable-layers/README.md index 70fb0836..1b5ef16c 100644 --- a/docs/modules/editable-layers/README.md +++ b/docs/modules/editable-layers/README.md @@ -2,15 +2,15 @@ Provides editable and interactive map overlay layers, built using the power of [deck.gl](https://deck.gl/). -History +## History A fork of @nebula.gl. nebula.gl is an important part of the deck.gl ecosystem but the repository has lacked maintainers for several years and the repository no longer accepts external contributions. -# What's New +## What's New This page contains highlights of each `editable-layers` release. -## editable-layers v9.0 +### editable-layers v9.0 - The code has been updated to work with deck.gl v9. @@ -26,21 +26,12 @@ This page contains highlights of each `editable-layers` release. | `react-map-gl-draw` | Non-deck-wrapper | => NOT FORKED | -Release date: TBD +### editable-layers v0.0.1 -### Draw Rectangle From Center Mode +Release date: TBD - new `DrawRectangleFromCenterMode`. User can draw a new rectangular `Polygon` feature by clicking the center, then along a corner of the rectangle. - -### Translate mode - - `screenSpace` option can be provided in the `modeConfig` of Translate mode so the features will be translated without distortion in screen space. - -### Modify mode - - `lockRectangles` option can be provided in the `modeConfig` object for ModifyMode, so the features with `properties.shape === 'Rectangle'` will preserve rectangular shape. - -### EditableGeojsonLayer - - `pickingLineWidthExtraPixels` property to specify additional line width in pixels for picking. Can be useful when `EditableGeojsonLayer` is over a deck.gl layer and precise picking is problematic, and when usage of `pickingDepth` introduces performance issues. diff --git a/docs/modules/react-graph-layers/sidebar.json b/docs/modules/react-graph-layers/sidebar.json index d498061c..f1a63c4c 100644 --- a/docs/modules/react-graph-layers/sidebar.json +++ b/docs/modules/react-graph-layers/sidebar.json @@ -1,6 +1,6 @@ { "type": "category", - "label": "@deck.gl-community/react-graph-layers", + "label": "deck-react-graph-layers", "items": [ "modules/react-graph-layers/README", { diff --git a/docs/whats-new.md b/docs/whats-new.md index 22f2dc2c..9685cf6c 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -1,6 +1,6 @@ # What's New -## deck.gl v9 compatible releases +The following releases are deck.gl v9 compatible ### `@deck.gl-community/graph-layers` v9.0.0 @@ -23,7 +23,7 @@ This new module is a fork of Uber's no longer maintained @nebula.gl framework.is --- -## deck.gl v8 Compatible Releases +Releases below are deck.gl v8 compatible > Support for the v8 ecosystem is not a goal, anything below is available strictly on an as-is basis. diff --git a/website/src/docs-sidebar.js b/website/src/docs-sidebar.js index 6f5359aa..eba89365 100644 --- a/website/src/docs-sidebar.js +++ b/website/src/docs-sidebar.js @@ -27,15 +27,15 @@ const sidebars = { }, { type: 'category', - label: 'Basemaps', - items: [bingMapsDocs] + label: 'Layer Packs', + items: [layerDocs, editableLayerDocs, graphLayerDocs] }, { type: 'category', - label: 'Layer Packs', - items: [bingMapsDocs, layerDocs, editableLayerDocs, graphLayerDocs] + label: 'Basemaps', + items: [bingMapsDocs] }, - {label: 'React Bindings', items: [reactDocs, reactGraphDocs]} + {type: 'category', label: 'React Bindings', items: [reactDocs, reactGraphDocs]} ] }; From 9520912a8eebb182af76ac3decb11f72ce54acf4 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 13:05:34 -0400 Subject: [PATCH 2/9] wip --- docs/README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3f378f7c..45582c51 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,28 +1,30 @@ -# Community Modules +# Introduction -This repository contains a collection of community supported modules for [deck.gl](https://deck.gl), that are intended to complement the various modules already provided by the core deck.gl framework. Some modules type are: +This repository contains a collection of community supported modules for [deck.gl](https://deck.gl), that are intended to complement the various modules already provided by the core deck.gl framework. While any module that is properly scoped and of sufficient value to the community could be a candidate for this repository, common modules type are: -- additional layer packs -- additional base map integrations -- react bindings +- additional **layer packs** (beyond the various layer packs available in deck.gl) +- additional **base map** integrations (beyond the integrations supported by deck.gl) +- additional **react** bindings (beyond the `@deck.gl/react` module). ## Support -Community modules are not officially supported by the deck.gl team, but have at least some intermittent, part-time support from one or more community members. +Community modules are not officially supported by the core deck.gl maintainers, but have at least some intermittent, part-time support from one or more community members. -Note that the continued inclusion of each module into this repository depends to a large extent on whether there is sufficient community support for the module. Note that modules can be removed from this repository if the core deck.gl team feels that the community is no longer able to provide sufficient support. +Note that the continued inclusion of each module into this repository depends to a large extent on whether there is sufficient community support for the module. Modules can be removed from this repository if the core deck.gl team feels that the community is no longer able to provide sufficient support. If a module was to be removed, applications can of course copy the module's source code, but will need to maintain the code on their own. -## Contributing a module +## Contributing If you have a module that you think could fit into this repository, please start by opening a GitHub issue to start a discussion, or reach out in the OpenJS slack. -## Upstreaming to deck.gl? +## Upstreaming + +On rare occasions, a new component or module may be "upstreamed" into the core deck.gl repository. There is a high bar when adding new code to the main deck.gl repository. The deck.gl-community repository is sometimes used to prepare (incubate) new software components so that they are ready to be added to deck.gl. -Therefore when proposing the addition of a new component, such as a new deck.gl layer, +Therefore when proposing the addition of a new component (such as a new deck.gl layer), to the core deck.gl maintainers, it is helpful to be able to prepare the component in a monorepo environment that is similar to the deck.gl repo, complete with tests, documentation and examples. This can avoid a length and frustrating review process in the deck.gl repo. -To be clear, most components in this repository will never be added to the main deck.gl repository. +To set expectations, most components in this repository will never be added to the main deck.gl repository. From 6bb337ad4c1331ce0d8198ba3bd892936bc7a2c0 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 13:13:54 -0400 Subject: [PATCH 3/9] docs --- docs/modules/editable-layers/README.md | 4 ++++ .../editable-layers/developer-guide/get-started.md | 2 +- docs/modules/editable-layers/sidebar.json | 8 +------- docs/modules/graph-layers/README.md | 3 +++ docs/modules/layers/README.md | 5 ++++- website/src/docs-sidebar.js | 2 +- 6 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/modules/editable-layers/README.md b/docs/modules/editable-layers/README.md index 1b5ef16c..8833cce3 100644 --- a/docs/modules/editable-layers/README.md +++ b/docs/modules/editable-layers/README.md @@ -1,5 +1,9 @@ # Overview +![deck.gl](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") +![WebGPU](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") + + Provides editable and interactive map overlay layers, built using the power of [deck.gl](https://deck.gl/). ## History diff --git a/docs/modules/editable-layers/developer-guide/get-started.md b/docs/modules/editable-layers/developer-guide/get-started.md index 40281ea9..0eec8f56 100644 --- a/docs/modules/editable-layers/developer-guide/get-started.md +++ b/docs/modules/editable-layers/developer-guide/get-started.md @@ -1,4 +1,4 @@ -# Developer Guide +# Get Started ## Installation diff --git a/docs/modules/editable-layers/sidebar.json b/docs/modules/editable-layers/sidebar.json index fe7e3a9d..2c1c82fd 100644 --- a/docs/modules/editable-layers/sidebar.json +++ b/docs/modules/editable-layers/sidebar.json @@ -3,13 +3,7 @@ "label": "deck.gl-community/editable-layers", "items": [ "modules/editable-layers/README", - { - "type": "category", - "label": "Developer Guide", - "items": [ - "modules/editable-layers/developer-guide/get-started" - ] - }, + "modules/editable-layers/developer-guide/get-started", { "type": "category", "label": "Layers", diff --git a/docs/modules/graph-layers/README.md b/docs/modules/graph-layers/README.md index 75e2117a..9db90b92 100644 --- a/docs/modules/graph-layers/README.md +++ b/docs/modules/graph-layers/README.md @@ -1,5 +1,8 @@ # Overview +![deck.gl](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") +![WebGPU](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") + `graph-layers` is a deck.gl layer pack for GPU-powered visualization of large graphs. With graph-layers, developers can build various type of graph/network applications with minimum effort. The composable API enables highly customizable graph visualization by leveraging or even extending the provided graph *styles* and *layout algorithms*. diff --git a/docs/modules/layers/README.md b/docs/modules/layers/README.md index 84d8d420..859b2dcd 100644 --- a/docs/modules/layers/README.md +++ b/docs/modules/layers/README.md @@ -1,5 +1,8 @@ # Overview +![deck.gl](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") +![WebGPU](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") + This module provides a suite of non-official layers for [deck.gl](https://deck.gl). ## Installation @@ -14,7 +17,7 @@ Various layers developed by deck.gl maintainers that could be of use to others. ## What's New -### `@deck.gl-community/layers` v8.0.0 +### `@deck.gl-community/layers` v0.0.0 Release date: 2023 diff --git a/website/src/docs-sidebar.js b/website/src/docs-sidebar.js index eba89365..63b5a276 100644 --- a/website/src/docs-sidebar.js +++ b/website/src/docs-sidebar.js @@ -27,7 +27,7 @@ const sidebars = { }, { type: 'category', - label: 'Layer Packs', + label: 'Layers', items: [layerDocs, editableLayerDocs, graphLayerDocs] }, { From 5bfb667588a3c0ee8c86ae12555d988c2be15145 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 13:44:55 -0400 Subject: [PATCH 4/9] wip --- .../api-reference/edit-modes.md | 169 +++++++++++------- docs/modules/editable-layers/sidebar.json | 10 +- .../api-reference/graphgl.md | 2 +- .../api-reference/viewport.md | 21 --- docs/modules/react-graph-layers/sidebar.json | 3 +- .../react/developer-guide/get-started.md | 16 +- .../react/developer-guide/html-overlays.md | 18 -- docs/modules/react/sidebar.json | 14 +- 8 files changed, 131 insertions(+), 122 deletions(-) delete mode 100644 docs/modules/react-graph-layers/api-reference/viewport.md delete mode 100644 docs/modules/react/developer-guide/html-overlays.md diff --git a/docs/modules/editable-layers/api-reference/edit-modes.md b/docs/modules/editable-layers/api-reference/edit-modes.md index eb275e89..185fcf80 100644 --- a/docs/modules/editable-layers/api-reference/edit-modes.md +++ b/docs/modules/editable-layers/api-reference/edit-modes.md @@ -1,14 +1,16 @@ -# Editing Modes +# Editor Modes `EditMode`s provide a way of handling user interactions in order to manipulate GeoJSON features and geometries. The following built-in `EditMode`s are provided by: -## [ViewMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/view-mode.ts) +## ViewMode No edits are possible, but selection is still possible. -## [ModifyMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/modify-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/view-mode.ts) + +## ModifyMode User can move existing points, add intermediate points along lines, and remove points. @@ -17,7 +19,7 @@ The following options can be provided in the `modeConfig` object for ModifyMode: - `lockRectangles` (optional): `` - If `true`, features with `properties.shape === 'Rectangle'` will preserve rectangular shape. -### Edit Context +Callbacks: `editContext` argument to the `onEdit` callback contains the following properties: @@ -25,19 +27,29 @@ The following options can be provided in the `modeConfig` object for ModifyMode: - `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the edited position -## [ExtrudeMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/extrude-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/modify-mode.ts) + + +## ExtrudeMode User can move edge. Click and drag from anywhere between 2 points in edge. -## [ScaleMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/scale-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/extrude-mode.ts) + + +## ScaleMode User can scale a feature about its centroid by clicking and dragging (inward or outward) the selected geometry. This mode supports multiple selections. -## [RotateMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/rotate-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/scale-mode.ts) + +## RotateMode User can rotate a feature about its centroid by clicking and dragging the selected geometry. This mode supports multiple selections. -## [TranslateMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/translate-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/rotate-mode.ts) + +## TranslateMode The user can move a feature by selecting one or more features and dragging anywhere within the screen. _Additionally, the user can initiate snapping by clicking and dragging the selected feature's vertex handles. If the vertex handle is close enough to another feature's vertex, the two features will snap together._ @@ -46,35 +58,43 @@ The following options can be provided in the `modeConfig` object for TranslateMo - `screenSpace` (optional): `` - If `true`, the features will be translated without distortion in screen space. -## [TransformMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/transform-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/translate-mode.ts) + +## TransformMode A single mode that provides translating, rotating, and scaling capabilities. Translation can be performed by clicking and dragging the selected feature itself. Rotating can be performed by clicking and dragging the top-most edit handle around a centroid pivot. Scaling can be performed by clicking and dragging one of the corner edit handles. Just like the individual modes, this mode supports multiple selections and feature snapping. -## [DuplicateMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/duplicate-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/transform-mode.ts) + +## DuplicateMode User can duplicate and translate a feature by clicking selected feature and dragging anywhere on the screen. This mode is extends TranslateMode. This mode supports multiple selections. -## [DrawPointMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-point-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/duplicate-mode.ts) + +## DrawPointMode User can draw a new `Point` feature by clicking where the point is to be. -## [DrawLineStringMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-line-string-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-point-mode.ts) + +## DrawLineStringMode User can draw a new `LineString` feature by clicking positions to add. User finishes drawing by double-clicking. -## [ExtendLineStringMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/extend-line-string-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-line-string-mode.ts) -User can extend an existing `LineString` feature by clicking positions to add. A single `LineString` feature must be selected for this mode. +## ExtendLineStringMode -### ModeConfig +User can extend an existing `LineString` feature by clicking positions to add. A single `LineString` feature must be selected for this mode. The following options can be provided in the `modeConfig` object: - `drawAtFront` (optional): `` - If `true`, will extend from the "beginning" of the line, i.e. relative to the start of the coordinates array. -### Edit Context +Callback parameters `editContext` argument to the `onEdit` callback contains the following properties: @@ -82,22 +102,26 @@ The following options can be provided in the `modeConfig` object: - `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the added position -## [ResizeCircleMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/resize-circle-mode.js) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/extend-line-string-mode.ts) + +## ResizeCircleMode User can resize an existing circular Polygon feature by clicking and dragging along the ring. -## [DrawPolygonMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-polygon-mode.js) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/resize-circle-mode.js) + +## DrawPolygonMode User can draw a new `Polygon` feature by clicking positions to add then closing the polygon (or double-clicking). -### ModeConfig +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-polygon-mode.js) The following options can be provided in the `modeConfig` object: - `preventOverlappingLines` (optional): `boolean` - If `true`, it will not be possible to add a polygon point if the current line overlaps any other lines on the same polygon. -### Edit Context +Callback parameters `editContext` argument to the `onEdit` callback contains the following properties: @@ -105,14 +129,18 @@ The following options can be provided in the `modeConfig` object: - `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the added position -## [Draw90DegreePolygonMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-90degree-polygon-mode.ts) +## Draw90DegreePolygonMode User can draw a new `Polygon` feature with 90 degree corners (right angle) by clicking positions to add then closing the polygon (or double-clicking). After clicking the 2 points, the draw mode guides/allows to have right angle polygon. -## [DrawPolygonByDraggingMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-polygon-by-dragging-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-90degree-polygon-mode.ts) + +## DrawPolygonByDraggingMode User can draw a new `Polygon` feature by dragging (similar to the lasso tool commonly found in photo editing software). +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-polygon-by-dragging-mode.ts) + ### ModeConfig The following options can be provided in the `modeConfig` object: @@ -120,10 +148,12 @@ The following options can be provided in the `modeConfig` object: - `throttleMs` (optional): `number` - If provided, the dragging function will be throttled by the specified number of milliseconds. -## [DrawRectangleMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-rectangle-mode.ts) +## DrawRectangleMode User can draw a new rectangular `Polygon` feature by clicking two opposing corners of the rectangle. +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-mode.ts) + ### ModeConfig The following options can be provided in the `modeConfig` object: @@ -131,42 +161,43 @@ The following options can be provided in the `modeConfig` object: - `dragToDraw` (optional): `boolean` - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. -## [DrawRectangleFromCenterMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-rectangle-from-center-mode.ts) - +## DrawRectangleFromCenterMode User can draw a new rectangular `Polygon` feature by clicking the center then along a corner of the rectangle. -### ModeConfig - The following options can be provided in the `modeConfig` object: - `dragToDraw` (optional): `boolean` - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. -## [DrawRectangleUsingThreePointsMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-rectangle-using-three-points-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-from-center-mode.ts) + +## DrawRectangleUsingThreePointsMode User can draw a new rectangular `Polygon` feature by clicking three corners of the rectangle. -## [DrawSquareMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-square-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-using-three-points-mode.ts) + +## DrawSquareMode User can draw a new square-shaped `Polygon` feature by clicking two opposing corners of the square. -## [DrawSquareFromCenterMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-square-from-center-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-square-mode.ts) + +## DrawSquareFromCenterMode User can draw a new square-shaped `Polygon` feature by clicking the center and then along one of the corners of the square. -### ModeConfig +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-square-from-center-mode..ts) The following options can be provided in the `modeConfig` object: - `dragToDraw` (optional): `boolean` - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. -## [DrawCircleFromCenterMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-circle-from-center-mode.ts) +## DrawCircleFromCenterMode User can draw a new circular `Polygon` feature by clicking the center then along the ring. -### ModeConfig - The following options can be provided in the `modeConfig` object: - `steps` (optional): `x ` @@ -174,11 +205,11 @@ The following options can be provided in the `modeConfig` object: - `dragToDraw` (optional): `boolean` - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. -## [DrawCircleByDiameterMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-circle-by-diameter-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-circle-from-center-mode..ts) -User can draw a new circular `Polygon` feature by clicking the two ends of its diameter. +## DrawCircleByDiameterMode -### ModeConfig +User can draw a new circular `Polygon` feature by clicking the two ends of its diameter. The following options can be provided in the `modeConfig` object: @@ -187,7 +218,9 @@ The following options can be provided in the `modeConfig` object: - `dragToDraw` (optional): `boolean` - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. -## [DrawEllipseByBoundingBoxMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-ellipse-by-bounding-box-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-circle-by-diameter-mode..ts) + +## DrawEllipseByBoundingBoxMode User can draw a new ellipse shape `Polygon` feature by clicking two corners of bounding box. @@ -198,11 +231,15 @@ The following options can be provided in the `modeConfig` object: - `dragToDraw` (optional): `boolean` - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. -## [DrawEllipseUsingThreePointsMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/draw-ellipse-using-three-points-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-ellipse-by-bounding-box-mode.ts) + +## DrawEllipseUsingThreePointsMode User can draw a new ellipse shape `Polygon` feature by clicking center and two corners of the ellipse. -## [SplitPolygonMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/split-polygon-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-ellipse-using-three-points-mode.ts) + +## SplitPolygonMode User can split a polygon by drawing a new `LineString` feature on top of the polygon. @@ -210,11 +247,11 @@ User can split a polygon by drawing a new `LineString` feature on top of the pol - If the clicked position is inside the polygon, it will not split the polygon -## [MeasureDistanceMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/measure-distance-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/split-polygon-mode.ts) -User can measure a distance between two points. +## MeasureDistanceMode -### ModeConfig +User can measure a distance between two points. The following options can be provided in the `modeConfig` object: @@ -238,11 +275,11 @@ The following options can be provided in the `modeConfig` object: - If true, the measurement tooltips appear on the middle of their respective line segments rather than at the end - Default: `false` -## [MeasureAreaMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/measure-area-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-distance-mode.ts) -User can measure an area by drawing an arbitrary polygon. +## MeasureAreaMode -### ModeConfig +User can measure an area by drawing an arbitrary polygon. The following options can be provided in the `modeConfig` object: @@ -255,11 +292,11 @@ The following options can be provided in the `modeConfig` object: - Function to call as measurements are calculated - Default: `undefined` -## [MeasureAngleMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/measure-angle-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-area-mode.ts) -User can measure an angle by drawing two lines. +## MeasureAngleMode -### ModeConfig +User can measure an angle by drawing two lines. The following options can be provided in the `modeConfig` object: @@ -272,11 +309,12 @@ The following options can be provided in the `modeConfig` object: - Function to call as measurements are calculated - Default: `undefined` -## [ElevationMode](https://github.com/uber/@deck.gl-community/editable-layers/blob/master/modules/edit-modes/src/lib/elevation-mode.ts) +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-angle-mode.ts) -User can move a point up and down. -### ModeConfig +## ElevationMode + +User can move a point up and down. The following options can be provided in the `modeConfig` object: @@ -301,32 +339,29 @@ if (mode === 'elevation') { ElevationMode.calculateElevationChangeWithViewport(viewport, opts); } ``` - -## Boolean Operations - -For all polygon drawing modes, the following options can be provided in the `modeConfig` object: - -- `booleanOperation` (optional): `null|'union'|'difference'|'intersection'` - - If non-null, requires a single `Polygon` or `MultiPolygon` selection - - If `null`, the drawn `Polygon` is added as a new feature regardless of selection - - If `union`, the drawn `Polygon` is unioned with the selected geometry - - If `difference`, the drawn `Polygon` is subtracted from the selected geometry - - If `intersection`, the drawn `Polygon` is intersected with the selected geometry +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/elevation-mode.ts) ## Composite Mode Use `CompositeMode` to combine multiple modes. _Not all combinations are guaranteed to work._ -### Constructor - `new CompositeMode(modes, options = {})` - `modes`: `Array` Modes you want to combine. **Order is very important.** - `options` (optional): Options to be added later. -### Example - ``` new CompositeMode([new DrawLineStringMode(), new ModifyMode()]) ``` + +## Boolean Operations + +For all polygon drawing modes, the following options can be provided in the `modeConfig` object: + +- `booleanOperation` (optional): `null|'union'|'difference'|'intersection'` + - If non-null, requires a single `Polygon` or `MultiPolygon` selection + - If `null`, the drawn `Polygon` is added as a new feature regardless of selection + - If `union`, the drawn `Polygon` is unioned with the selected geometry + - If `difference`, the drawn `Polygon` is subtracted from the selected geometry + - If `intersection`, the drawn `Polygon` is intersected with the selected geometry diff --git a/docs/modules/editable-layers/sidebar.json b/docs/modules/editable-layers/sidebar.json index 2c1c82fd..ff4f2b3e 100644 --- a/docs/modules/editable-layers/sidebar.json +++ b/docs/modules/editable-layers/sidebar.json @@ -14,17 +14,17 @@ "modules/editable-layers/api-reference/layers/mesh-layer" ] }, + { + "type": "category", + "label": "EditModes", + "items": ["modules/editable-layers/api-reference/edit-modes"] + }, { "type": "category", "label": "Shader Modules", "items": [ "modules/editable-layers/api-reference/shader-modules/outline" ] - }, - { - "type": "category", - "label": "Modes", - "items": ["modules/editable-layers/api-reference/edit-modes"] } ] } diff --git a/docs/modules/react-graph-layers/api-reference/graphgl.md b/docs/modules/react-graph-layers/api-reference/graphgl.md index cbb1dffb..390a8273 100644 --- a/docs/modules/react-graph-layers/api-reference/graphgl.md +++ b/docs/modules/react-graph-layers/api-reference/graphgl.md @@ -1,4 +1,4 @@ -# GraphGL (React) +# GraphGL

diff --git a/docs/modules/react-graph-layers/api-reference/viewport.md b/docs/modules/react-graph-layers/api-reference/viewport.md deleted file mode 100644 index addd22d8..00000000 --- a/docs/modules/react-graph-layers/api-reference/viewport.md +++ /dev/null @@ -1,21 +0,0 @@ -# Viewport (React) - -### initialViewState (Object, optional) - -```js -initialViewState={{ - target: [0, 0], - zoom: 1, -}} -``` - - target ([x: Number, y: Number], optional): The target origin to the center of the view. - - zoom (Number, optional): The zoom level of the view. - -### `minZoom` (Number, optional) -A minimum scale factor for zoom level of the graph. - -### `maxZoom` (Number, optional) -A maximum scale factor for zoom level of the graph. - -### `viewportPadding` (Number, optional) -Padding for fitting entire graph in the screen. (pixel) diff --git a/docs/modules/react-graph-layers/sidebar.json b/docs/modules/react-graph-layers/sidebar.json index f1a63c4c..c169485f 100644 --- a/docs/modules/react-graph-layers/sidebar.json +++ b/docs/modules/react-graph-layers/sidebar.json @@ -7,8 +7,7 @@ "type": "category", "label": "GraphGL", "items": [ - "modules/react-graph-layers/api-reference/graphgl", - "modules/react-graph-layers/api-reference/viewport" + "modules/react-graph-layers/api-reference/graphgl" ] } ] diff --git a/docs/modules/react/developer-guide/get-started.md b/docs/modules/react/developer-guide/get-started.md index b3968dde..8049953b 100644 --- a/docs/modules/react/developer-guide/get-started.md +++ b/docs/modules/react/developer-guide/get-started.md @@ -1,8 +1,22 @@ # Get Started -### Overlays +## Overlays The overlay layers are based on HTML and rendered by the browser. You can use them for complicated objects that follow map points. They are less performant but more flexible. For more details see [Using Html Overlays](/docs/modules/react/api-reference/overlays/html-overlay) + +HTML overlays are very easy to use and take advantage of [react's architecture](https://reactjs.org/docs/). + +```jsx + + {title} + +``` + +Checkout the Unesco World Heritage example. + +See Also +- [Html Overlay](/docs/modules/react/api-reference/overlays/html-overlay) +- [Html Overlay Item](/docs/modules/react/api-reference/overlays/html-overlay-item) diff --git a/docs/modules/react/developer-guide/html-overlays.md b/docs/modules/react/developer-guide/html-overlays.md deleted file mode 100644 index 4eb512dd..00000000 --- a/docs/modules/react/developer-guide/html-overlays.md +++ /dev/null @@ -1,18 +0,0 @@ -# Using Html Overlays - -HTML overlays are very easy to use and take advantage of [react's architecture](https://reactjs.org/docs/). - -```jsx - - {title} - -``` - -## Example - -Checkout the Unesco World Heritage example. - -## See Also - -- [Html Overlay](/docs/modules/react/api-reference/overlays/html-overlay) -- [Html Overlay Item](/docs/modules/react/api-reference/overlays/html-overlay-item) diff --git a/docs/modules/react/sidebar.json b/docs/modules/react/sidebar.json index 939c9600..7bad71da 100644 --- a/docs/modules/react/sidebar.json +++ b/docs/modules/react/sidebar.json @@ -3,21 +3,21 @@ "label": "deck.gl-community/react", "items": [ "modules/react/README", + "modules/react/developer-guide/get-started", { "type": "category", - "label": "Developer Guide", + "label": "Overlays", "items": [ - "modules/react/developer-guide/get-started", - "modules/react/developer-guide/html-overlays" + "modules/react/api-reference/overlays/html-overlay", + "modules/react/api-reference/overlays/html-cluster-overlay", + "modules/react/api-reference/overlays/html-overlay-item" ] }, { "type": "category", - "label": "Overlays", + "label": "Components", "items": [ - "modules/react/api-reference/overlays/html-overlay", - "modules/react/api-reference/overlays/html-cluster-overlay", - "modules/react/api-reference/overlays/html-overlay-item" + "modules/react/api-reference/viewport" ] } ] From d33637c99bf48f06296924f64636ce28bf34f5a8 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 13:45:30 -0400 Subject: [PATCH 5/9] wip --- docs/modules/react/api-reference/viewport.md | 21 ++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 docs/modules/react/api-reference/viewport.md diff --git a/docs/modules/react/api-reference/viewport.md b/docs/modules/react/api-reference/viewport.md new file mode 100644 index 00000000..cce2aacc --- /dev/null +++ b/docs/modules/react/api-reference/viewport.md @@ -0,0 +1,21 @@ +# Viewport + +### initialViewState (Object, optional) + +```js +initialViewState={{ + target: [0, 0], + zoom: 1, +}} +``` + - target ([x: Number, y: Number], optional): The target origin to the center of the view. + - zoom (Number, optional): The zoom level of the view. + +### `minZoom` (Number, optional) +A minimum scale factor for zoom level of the graph. + +### `maxZoom` (Number, optional) +A maximum scale factor for zoom level of the graph. + +### `viewportPadding` (Number, optional) +Padding for fitting entire graph in the screen. (pixel) From 7e0bdf9136b68d6fc5c990350887a2f715e28412 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 13:49:16 -0400 Subject: [PATCH 6/9] wip --- .../editable-layers/api-reference/layers/mesh-layer.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/modules/editable-layers/api-reference/layers/mesh-layer.md b/docs/modules/editable-layers/api-reference/layers/mesh-layer.md index 7b556d4d..2aa30253 100644 --- a/docs/modules/editable-layers/api-reference/layers/mesh-layer.md +++ b/docs/modules/editable-layers/api-reference/layers/mesh-layer.md @@ -1,5 +1,7 @@ # MeshLayer +> TO BE REPLACED with `@deck.gl/mesh-layers` + The Mesh Layer renders a number of arbitrary geometries. For example, a fleet of 3d cars each with a position and an orientation over the map. ```js @@ -122,7 +124,3 @@ The color of each object. Only used if `texture` is empty. Whether the layer should be rendered in high-precision 64-bit mode ##### `lightSettings` (Object, optional) - -**TO BE REPLACED** - -With `@deck.gl/mesh-layers` From 711b2474d9c25189f94fb6fdf3b36c2108d93815 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 16:23:06 -0400 Subject: [PATCH 7/9] wip --- docs/modules/editable-layers/README.md | 17 +- .../api-reference/edit-modes.md | 71 +------ .../api-reference/edit-modes/core-modes.md | 34 ++++ .../api-reference/edit-modes/draw-modes.md | 185 ++++++++++++++++++ .../edit-modes/measurement-modes.md | 95 +++++++++ .../edit-modes/transform-modes.md | 60 ++++++ .../developer-guide/get-started.md | 34 +--- docs/modules/editable-layers/sidebar.json | 9 +- docs/modules/graph-layers/README.md | 4 +- docs/modules/layers/README.md | 4 +- 10 files changed, 405 insertions(+), 108 deletions(-) create mode 100644 docs/modules/editable-layers/api-reference/edit-modes/core-modes.md create mode 100644 docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md create mode 100644 docs/modules/editable-layers/api-reference/edit-modes/measurement-modes.md create mode 100644 docs/modules/editable-layers/api-reference/edit-modes/transform-modes.md diff --git a/docs/modules/editable-layers/README.md b/docs/modules/editable-layers/README.md index 8833cce3..e733f3b1 100644 --- a/docs/modules/editable-layers/README.md +++ b/docs/modules/editable-layers/README.md @@ -1,11 +1,21 @@ # Overview -![deck.gl](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") -![WebGPU](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") - +![deck.gl v9](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") +![WebGPU not supported](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") Provides editable and interactive map overlay layers, built using the power of [deck.gl](https://deck.gl/). +## Design Goals + +`@deck.gl-community/editable-layers` aspires to be an ultra-performant, fully 3D-enabled GeoJSON editing system primarily focused on geospatial editing use cases. + +- Maximal rendering and editing performance. +- Editing at 60fps (e.g. dragging sub objects) in GeoJSON payloads with 100K features (points, lines or polygons). +- Handle GeoJSON corner cases (e.g. automatically changing object types from `Polygon` to `MultiPolygon` when addition polygons are added). +- Fully 3D enabled (Can use WebGL z-buffer so that lines being rendered are properly occluded by other geometry). +- Seamless integration with deck.gl, allowing for GeoJSON editing to be interleaved with rich 3D visualizations. +- Handle event handling, including touch screen support. + ## History A fork of @nebula.gl. nebula.gl is an important part of the deck.gl ecosystem but the repository has lacked maintainers for several years and the repository no longer accepts external contributions. @@ -16,7 +26,6 @@ This page contains highlights of each `editable-layers` release. ### editable-layers v9.0 - - The code has been updated to work with deck.gl v9. - The module structure has been simplified via the module mapping in the table below. diff --git a/docs/modules/editable-layers/api-reference/edit-modes.md b/docs/modules/editable-layers/api-reference/edit-modes.md index 185fcf80..8ca22bb2 100644 --- a/docs/modules/editable-layers/api-reference/edit-modes.md +++ b/docs/modules/editable-layers/api-reference/edit-modes.md @@ -1,78 +1,9 @@ -# Editor Modes +# Edit Modes `EditMode`s provide a way of handling user interactions in order to manipulate GeoJSON features and geometries. The following built-in `EditMode`s are provided by: -## ViewMode - -No edits are possible, but selection is still possible. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/view-mode.ts) - -## ModifyMode - -User can move existing points, add intermediate points along lines, and remove points. - -The following options can be provided in the `modeConfig` object for ModifyMode: - -- `lockRectangles` (optional): `` - - If `true`, features with `properties.shape === 'Rectangle'` will preserve rectangular shape. - -Callbacks: - -`editContext` argument to the `onEdit` callback contains the following properties: - -- `positionIndexes` (Array): An array of numbers representing the indexes of the edited position within the feature's `coordinates` array - -- `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the edited position - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/modify-mode.ts) - - -## ExtrudeMode - -User can move edge. Click and drag from anywhere between 2 points in edge. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/extrude-mode.ts) - - -## ScaleMode - -User can scale a feature about its centroid by clicking and dragging (inward or outward) the selected geometry. This mode supports multiple selections. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/scale-mode.ts) - -## RotateMode - -User can rotate a feature about its centroid by clicking and dragging the selected geometry. This mode supports multiple selections. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/rotate-mode.ts) - -## TranslateMode - -The user can move a feature by selecting one or more features and dragging anywhere within the screen. -_Additionally, the user can initiate snapping by clicking and dragging the selected feature's vertex handles. If the vertex handle is close enough to another feature's vertex, the two features will snap together._ -The following options can be provided in the `modeConfig` object for TranslateMode: - -- `screenSpace` (optional): `` - - If `true`, the features will be translated without distortion in screen space. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/translate-mode.ts) - -## TransformMode - -A single mode that provides translating, rotating, and scaling capabilities. Translation can be performed by clicking and dragging the selected feature itself. Rotating can be performed by clicking and dragging the top-most edit handle around a centroid pivot. Scaling can be performed by clicking and dragging one of the corner edit handles. Just like the individual modes, this mode supports multiple selections and feature snapping. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/transform-mode.ts) - -## DuplicateMode - -User can duplicate and translate a feature by clicking selected feature and dragging anywhere on the screen. -This mode is extends TranslateMode. This mode supports multiple selections. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/duplicate-mode.ts) - ## DrawPointMode User can draw a new `Point` feature by clicking where the point is to be. diff --git a/docs/modules/editable-layers/api-reference/edit-modes/core-modes.md b/docs/modules/editable-layers/api-reference/edit-modes/core-modes.md new file mode 100644 index 00000000..81087cb2 --- /dev/null +++ b/docs/modules/editable-layers/api-reference/edit-modes/core-modes.md @@ -0,0 +1,34 @@ +# Editor Modes + +`EditMode`s provide a way of handling user interactions in order to manipulate GeoJSON features and geometries. + +The most basic modes are: + +## ViewMode + +No edits are possible, but selection is still possible. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/view-mode.ts) + +## DuplicateMode + +User can duplicate and translate a feature by clicking selected feature and dragging anywhere on the screen. +This mode is extends TranslateMode. This mode supports multiple selections. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/duplicate-mode.ts) + + +## Composite Mode + +Use `CompositeMode` to combine multiple modes. +_Not all combinations are guaranteed to work._ + +`new CompositeMode(modes, options = {})` + +- `modes`: `Array` Modes you want to combine. **Order is very important.** +- `options` (optional): Options to be added later. + +``` +new CompositeMode([new DrawLineStringMode(), new ModifyMode()]) +``` + diff --git a/docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md b/docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md new file mode 100644 index 00000000..6e6b355b --- /dev/null +++ b/docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md @@ -0,0 +1,185 @@ +# Editor Modes + +`EditMode`s provide a way of handling user interactions in order to manipulate GeoJSON features and geometries. + +## Draw configuration options + +Note that for all polygon drawing modes, the following options can also be provided in the `modeConfig` object: + +- `booleanOperation` (optional): `null|'union'|'difference'|'intersection'` + - If non-null, requires a single `Polygon` or `MultiPolygon` selection + - If `null`, the drawn `Polygon` is added as a new feature regardless of selection + - If `union`, the drawn `Polygon` is unioned with the selected geometry + - If `difference`, the drawn `Polygon` is subtracted from the selected geometry + - If `intersection`, the drawn `Polygon` is intersected with the selected geometry + +## DrawPointMode + +User can draw a new `Point` feature by clicking where the point is to be. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-point-mode.ts) + +## DrawLineStringMode + +User can draw a new `LineString` feature by clicking positions to add. User finishes drawing by double-clicking. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-line-string-mode.ts) + +## ExtendLineStringMode + +User can extend an existing `LineString` feature by clicking positions to add. A single `LineString` feature must be selected for this mode. + +The following options can be provided in the `modeConfig` object: + +- `drawAtFront` (optional): `` + - If `true`, will extend from the "beginning" of the line, i.e. relative to the start of the coordinates array. + +Callback parameters + +`editContext` argument to the `onEdit` callback contains the following properties: + +- `positionIndexes` (Array): An array of numbers representing the indexes of the added position within the feature's `coordinates` array + +- `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the added position + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/extend-line-string-mode.ts) + +## ResizeCircleMode + +User can resize an existing circular Polygon feature by clicking and dragging along the ring. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/resize-circle-mode.js) + +## DrawPolygonMode + +User can draw a new `Polygon` feature by clicking positions to add then closing the polygon (or double-clicking). + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-polygon-mode.js) + +The following options can be provided in the `modeConfig` object: + +- `preventOverlappingLines` (optional): `boolean` + - If `true`, it will not be possible to add a polygon point if the current line overlaps any other lines on the same polygon. + +Callback parameters + +`editContext` argument to the `onEdit` callback contains the following properties: + +- `positionIndexes` (Array): An array of numbers representing the indexes of the added position within the feature's `coordinates` array + +- `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the added position + +## Draw90DegreePolygonMode + +User can draw a new `Polygon` feature with 90 degree corners (right angle) by clicking positions to add then closing the polygon (or double-clicking). After clicking the 2 points, the draw mode guides/allows to have right angle polygon. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-90degree-polygon-mode.ts) + +## DrawPolygonByDraggingMode + +User can draw a new `Polygon` feature by dragging (similar to the lasso tool commonly found in photo editing software). + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-polygon-by-dragging-mode.ts) + +The following options can be provided in the `modeConfig` object: + +- `throttleMs` (optional): `number` + - If provided, the dragging function will be throttled by the specified number of milliseconds. + +## DrawRectangleMode + +User can draw a new rectangular `Polygon` feature by clicking two opposing corners of the rectangle. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-mode.ts) + +The following options can be provided in the `modeConfig` object: + +- `dragToDraw` (optional): `boolean` + - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. + +## DrawRectangleFromCenterMode +User can draw a new rectangular `Polygon` feature by clicking the center then along a corner of the rectangle. + +The following options can be provided in the `modeConfig` object: + +- `dragToDraw` (optional): `boolean` + - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-from-center-mode.ts) + +## DrawRectangleUsingThreePointsMode + +User can draw a new rectangular `Polygon` feature by clicking three corners of the rectangle. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-using-three-points-mode.ts) + +## DrawSquareMode + +User can draw a new square-shaped `Polygon` feature by clicking two opposing corners of the square. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-square-mode.ts) + +## DrawSquareFromCenterMode + +User can draw a new square-shaped `Polygon` feature by clicking the center and then along one of the corners of the square. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-square-from-center-mode..ts) + +The following options can be provided in the `modeConfig` object: + +- `dragToDraw` (optional): `boolean` + - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. + +## DrawCircleFromCenterMode + +User can draw a new circular `Polygon` feature by clicking the center then along the ring. + +The following options can be provided in the `modeConfig` object: + +- `steps` (optional): `x ` + - If steps: `x` means the circle will be drawn using `x` number of points. +- `dragToDraw` (optional): `boolean` + - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-circle-from-center-mode..ts) + +## DrawCircleByDiameterMode + +User can draw a new circular `Polygon` feature by clicking the two ends of its diameter. + +The following options can be provided in the `modeConfig` object: + +- `steps` (optional): `x ` + - If steps: `x` means the circle will be drawn using `x` number of points. +- `dragToDraw` (optional): `boolean` + - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-circle-by-diameter-mode..ts) + +## DrawEllipseByBoundingBoxMode + +User can draw a new ellipse shape `Polygon` feature by clicking two corners of bounding box. + +The following options can be provided in the `modeConfig` object: + +- `dragToDraw` (optional): `boolean` + - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-ellipse-by-bounding-box-mode.ts) + +## DrawEllipseUsingThreePointsMode + +User can draw a new ellipse shape `Polygon` feature by clicking center and two corners of the ellipse. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-ellipse-using-three-points-mode.ts) + +## SplitPolygonMode + +User can split a polygon by drawing a new `LineString` feature on top of the polygon. + +- If the first and the last click is outside the polygon, it will split the polygon + +- If the clicked position is inside the polygon, it will not split the polygon + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/split-polygon-mode.ts) + diff --git a/docs/modules/editable-layers/api-reference/edit-modes/measurement-modes.md b/docs/modules/editable-layers/api-reference/edit-modes/measurement-modes.md new file mode 100644 index 00000000..9405f150 --- /dev/null +++ b/docs/modules/editable-layers/api-reference/edit-modes/measurement-modes.md @@ -0,0 +1,95 @@ +# Measurement Modes + +A number of modes provide various measurement capabilities + +## MeasureDistanceMode + +User can measure a distance between two points. + +The following options can be provided in the `modeConfig` object: + +- `turfOptions` (Object, optional) + + - `options` object passed to turf's [distance](https://turfjs.org/docs/#distance) function + - Default: `undefined` + +- `formatTooltip` (Function, optional) + + - Function to format tooltip text (argument is the numeric distance) + - Default: `(distance) => parseFloat(distance).toFixed(2) + units` + +- `measurementCallback` (Function, optional) + + - Function to call as measurements are calculated + - Default: `undefined` + +- `centerTooltipsOnLine` (Boolean, optional) + + - If true, the measurement tooltips appear on the middle of their respective line segments rather than at the end + - Default: `false` + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-distance-mode.ts) + +## MeasureAreaMode + +User can measure an area by drawing an arbitrary polygon. + +The following options can be provided in the `modeConfig` object: + +- `formatTooltip` (Function, optional) + + - Function to format tooltip text (argument is the numeric area) + - Default: `(distance) => parseFloat(distance).toFixed(2) + units` + +- `measurementCallback` (Function, optional) + - Function to call as measurements are calculated + - Default: `undefined` + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-area-mode.ts) + +## MeasureAngleMode + +User can measure an angle by drawing two lines. + +The following options can be provided in the `modeConfig` object: + +- `formatTooltip` (Function, optional) + + - Function to format tooltip text (argument is the numeric area) + - Default: `(distance) => parseFloat(angle).toFixed(2) + units` + +- `measurementCallback` (Function, optional) + - Function to call as measurements are calculated + - Default: `undefined` + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-angle-mode.ts) + + +## ElevationMode + +User can move a point up and down. + +The following options can be provided in the `modeConfig` object: + +- `minElevation` (Number, optional) + + - The minimum elevation to allow + - Default: `0` + +- `maxElevation` (Number, optional) + + - The maximum elevation to allow + - Default: `20000` + +- `calculateElevationChange` (Function, optional) + - A function to use to calculate the elevation change in response to mouse movement + - Default: `10 * ` + - Configure to use movement based on viewport: + +```javascript +if (mode === 'elevation') { + modeConfig.calculateElevationChange = (opts) => + ElevationMode.calculateElevationChangeWithViewport(viewport, opts); +} +``` +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/elevation-mode.ts) diff --git a/docs/modules/editable-layers/api-reference/edit-modes/transform-modes.md b/docs/modules/editable-layers/api-reference/edit-modes/transform-modes.md new file mode 100644 index 00000000..59969676 --- /dev/null +++ b/docs/modules/editable-layers/api-reference/edit-modes/transform-modes.md @@ -0,0 +1,60 @@ +# Transform Modes + +An existing geometry can be modified with a variety of modes. + +## ModifyMode + +User can move existing points, add intermediate points along lines, and remove points. + +The following options can be provided in the `modeConfig` object for ModifyMode: + +- `lockRectangles` (optional): `` + - If `true`, features with `properties.shape === 'Rectangle'` will preserve rectangular shape. + +Callbacks: + +`editContext` argument to the `onEdit` callback contains the following properties: + +- `positionIndexes` (Array): An array of numbers representing the indexes of the edited position within the feature's `coordinates` array + +- `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the edited position + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/modify-mode.ts) + + +## ExtrudeMode + +User can move edge. Click and drag from anywhere between 2 points in edge. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/extrude-mode.ts) + + +## ScaleMode + +User can scale a feature about its centroid by clicking and dragging (inward or outward) the selected geometry. This mode supports multiple selections. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/scale-mode.ts) + +## RotateMode + +User can rotate a feature about its centroid by clicking and dragging the selected geometry. This mode supports multiple selections. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/rotate-mode.ts) + +## TranslateMode + +The user can move a feature by selecting one or more features and dragging anywhere within the screen. +_Additionally, the user can initiate snapping by clicking and dragging the selected feature's vertex handles. If the vertex handle is close enough to another feature's vertex, the two features will snap together._ +The following options can be provided in the `modeConfig` object for TranslateMode: + +- `screenSpace` (optional): `` + - If `true`, the features will be translated without distortion in screen space. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/translate-mode.ts) + +## TransformMode + +A single mode that provides translating, rotating, and scaling capabilities. Translation can be performed by clicking and dragging the selected feature itself. Rotating can be performed by clicking and dragging the top-most edit handle around a centroid pivot. Scaling can be performed by clicking and dragging one of the corner edit handles. Just like the individual modes, this mode supports multiple selections and feature snapping. + +[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/transform-mode.ts) + diff --git a/docs/modules/editable-layers/developer-guide/get-started.md b/docs/modules/editable-layers/developer-guide/get-started.md index 0eec8f56..493ac589 100644 --- a/docs/modules/editable-layers/developer-guide/get-started.md +++ b/docs/modules/editable-layers/developer-guide/get-started.md @@ -9,40 +9,18 @@ yarn add @deck.gl-community/editable-layers yarn add @deck.gl-community/react-editable-layers ``` -## Design Goals - -@deck.gl-community/editable-layers aspires to be an ultra-performant, fully 3D-enabled GeoJSON editing system primarily focused on geospatial editing use cases. - -- Maximal rendering and editing performance, without need for complex application logic (such as splitting data into subgroups etc). -- Target performance: Editing at 60fps (e.g. dragging sub objects) in GeoJSON payloads with 100K features (points, lines or polygons). -- Handles GeoJSON corner cases, e.g. automatically changing object types from `Polygon` to `MultiPolygon` when addition polygons are added. -- Fully 3D enabled (Can e.g. use WebGL z-buffer so that lines being rendered are properly occluded by other geometry). -- Seamless integration with deck.gl and all geospatial deck.gl layers, allowing for GeoJSON editing to be interleaved with rich 3D visualizations. -- Handle all aspects of event handling, including touch screen support. - -## Why use `editable-layers`? - -You should strongly consider `editable-layers` if: - -- You want a full-featured, ultra-high-performance editing solution for GeoJson. -- You are already using e.g. `deck.gl` or `react-map-gl`. - -You may want to look at alternatives if: - -- If you have very simple editing requirements (just a simple polygon etc) -- If you don't want to use `deck.gl` in your project. - -If `editable-layers` is more than what you need (e.g. in terms of bundle size), and you may want to look at other solutions, e.g. the simple polygon editor overlay being developed in react-map-gl. - -That said, if you are already using `deck.gl` the additional overhead of `editable-layers` is small, and the seamless integration with deck.gl should be valuable. - ## Quick Overview of the API ### EditableGeoJsonLayer [EditableGeoJsonLayer](/docs/modules/editable-layers/api-reference/layers/editable-geojson-layer) is implemented as a [deck.gl](https://deck.gl) layer. It provides the ability to view and edit multiple types of geometry formatted as [GeoJSON](https://tools.ietf.org/html/rfc7946) (an open standard format for geometry) including polygons, lines, and points. -#### Callbacks + +### Edit Modes + +TBA + +### Callbacks When there is the ability to edit, callbacks are provided to inform you of edits. diff --git a/docs/modules/editable-layers/sidebar.json b/docs/modules/editable-layers/sidebar.json index ff4f2b3e..9bbd7837 100644 --- a/docs/modules/editable-layers/sidebar.json +++ b/docs/modules/editable-layers/sidebar.json @@ -16,8 +16,13 @@ }, { "type": "category", - "label": "EditModes", - "items": ["modules/editable-layers/api-reference/edit-modes"] + "label": "Edit Modes", + "items": [ + "modules/editable-layers/api-reference/edit-modes/core-modes", + "modules/editable-layers/api-reference/edit-modes/draw-modes", + "modules/editable-layers/api-reference/edit-modes/transform-modes", + "modules/editable-layers/api-reference/edit-modes/measurement-modes" + ] }, { "type": "category", diff --git a/docs/modules/graph-layers/README.md b/docs/modules/graph-layers/README.md index 9db90b92..abd2d75a 100644 --- a/docs/modules/graph-layers/README.md +++ b/docs/modules/graph-layers/README.md @@ -1,7 +1,7 @@ # Overview -![deck.gl](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") -![WebGPU](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") +![deck.gl v9](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") +![WebGPU not supported](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") `graph-layers` is a deck.gl layer pack for GPU-powered visualization of large graphs. diff --git a/docs/modules/layers/README.md b/docs/modules/layers/README.md index 859b2dcd..dff45fe8 100644 --- a/docs/modules/layers/README.md +++ b/docs/modules/layers/README.md @@ -1,7 +1,7 @@ # Overview -![deck.gl](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") -![WebGPU](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") +![deck.gl v9](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square") +![WebGPU not supported](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square") This module provides a suite of non-official layers for [deck.gl](https://deck.gl). From b654a712218e93255ab791c7c7a20e523c35e6f3 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 16:24:59 -0400 Subject: [PATCH 8/9] wip --- .../editable-layers/api-reference/edit-modes/core-modes.md | 2 +- .../editable-layers/api-reference/edit-modes/draw-modes.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/editable-layers/api-reference/edit-modes/core-modes.md b/docs/modules/editable-layers/api-reference/edit-modes/core-modes.md index 81087cb2..9027ca17 100644 --- a/docs/modules/editable-layers/api-reference/edit-modes/core-modes.md +++ b/docs/modules/editable-layers/api-reference/edit-modes/core-modes.md @@ -1,4 +1,4 @@ -# Editor Modes +# Edit Modes `EditMode`s provide a way of handling user interactions in order to manipulate GeoJSON features and geometries. diff --git a/docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md b/docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md index 6e6b355b..261948d3 100644 --- a/docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md +++ b/docs/modules/editable-layers/api-reference/edit-modes/draw-modes.md @@ -1,4 +1,4 @@ -# Editor Modes +# Draw Modes `EditMode`s provide a way of handling user interactions in order to manipulate GeoJSON features and geometries. From e4b834ca5ef22784fe6f800cacd315b6726433e6 Mon Sep 17 00:00:00 2001 From: Ib Green Date: Mon, 15 Apr 2024 16:26:44 -0400 Subject: [PATCH 9/9] wip --- .../api-reference/edit-modes.md | 298 ------------------ 1 file changed, 298 deletions(-) delete mode 100644 docs/modules/editable-layers/api-reference/edit-modes.md diff --git a/docs/modules/editable-layers/api-reference/edit-modes.md b/docs/modules/editable-layers/api-reference/edit-modes.md deleted file mode 100644 index 8ca22bb2..00000000 --- a/docs/modules/editable-layers/api-reference/edit-modes.md +++ /dev/null @@ -1,298 +0,0 @@ -# Edit Modes - -`EditMode`s provide a way of handling user interactions in order to manipulate GeoJSON features and geometries. - -The following built-in `EditMode`s are provided by: - -## DrawPointMode - -User can draw a new `Point` feature by clicking where the point is to be. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-point-mode.ts) - -## DrawLineStringMode - -User can draw a new `LineString` feature by clicking positions to add. User finishes drawing by double-clicking. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-line-string-mode.ts) - -## ExtendLineStringMode - -User can extend an existing `LineString` feature by clicking positions to add. A single `LineString` feature must be selected for this mode. - -The following options can be provided in the `modeConfig` object: - -- `drawAtFront` (optional): `` - - If `true`, will extend from the "beginning" of the line, i.e. relative to the start of the coordinates array. - -Callback parameters - -`editContext` argument to the `onEdit` callback contains the following properties: - -- `positionIndexes` (Array): An array of numbers representing the indexes of the added position within the feature's `coordinates` array - -- `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the added position - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/extend-line-string-mode.ts) - -## ResizeCircleMode - -User can resize an existing circular Polygon feature by clicking and dragging along the ring. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/resize-circle-mode.js) - -## DrawPolygonMode - -User can draw a new `Polygon` feature by clicking positions to add then closing the polygon (or double-clicking). - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-polygon-mode.js) - -The following options can be provided in the `modeConfig` object: - -- `preventOverlappingLines` (optional): `boolean` - - If `true`, it will not be possible to add a polygon point if the current line overlaps any other lines on the same polygon. - -Callback parameters - -`editContext` argument to the `onEdit` callback contains the following properties: - -- `positionIndexes` (Array): An array of numbers representing the indexes of the added position within the feature's `coordinates` array - -- `position` (Array): An array containing the ground coordinates (i.e. [lng, lat]) of the added position - -## Draw90DegreePolygonMode - -User can draw a new `Polygon` feature with 90 degree corners (right angle) by clicking positions to add then closing the polygon (or double-clicking). After clicking the 2 points, the draw mode guides/allows to have right angle polygon. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-90degree-polygon-mode.ts) - -## DrawPolygonByDraggingMode - -User can draw a new `Polygon` feature by dragging (similar to the lasso tool commonly found in photo editing software). - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-polygon-by-dragging-mode.ts) - -### ModeConfig - -The following options can be provided in the `modeConfig` object: - -- `throttleMs` (optional): `number` - - If provided, the dragging function will be throttled by the specified number of milliseconds. - -## DrawRectangleMode - -User can draw a new rectangular `Polygon` feature by clicking two opposing corners of the rectangle. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-mode.ts) - -### ModeConfig - -The following options can be provided in the `modeConfig` object: - -- `dragToDraw` (optional): `boolean` - - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. - -## DrawRectangleFromCenterMode -User can draw a new rectangular `Polygon` feature by clicking the center then along a corner of the rectangle. - -The following options can be provided in the `modeConfig` object: - -- `dragToDraw` (optional): `boolean` - - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-from-center-mode.ts) - -## DrawRectangleUsingThreePointsMode - -User can draw a new rectangular `Polygon` feature by clicking three corners of the rectangle. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-rectangle-using-three-points-mode.ts) - -## DrawSquareMode - -User can draw a new square-shaped `Polygon` feature by clicking two opposing corners of the square. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-square-mode.ts) - -## DrawSquareFromCenterMode - -User can draw a new square-shaped `Polygon` feature by clicking the center and then along one of the corners of the square. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-square-from-center-mode..ts) - -The following options can be provided in the `modeConfig` object: - -- `dragToDraw` (optional): `boolean` - - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. - -## DrawCircleFromCenterMode - -User can draw a new circular `Polygon` feature by clicking the center then along the ring. - -The following options can be provided in the `modeConfig` object: - -- `steps` (optional): `x ` - - If steps: `x` means the circle will be drawn using `x` number of points. -- `dragToDraw` (optional): `boolean` - - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-circle-from-center-mode..ts) - -## DrawCircleByDiameterMode - -User can draw a new circular `Polygon` feature by clicking the two ends of its diameter. - -The following options can be provided in the `modeConfig` object: - -- `steps` (optional): `x ` - - If steps: `x` means the circle will be drawn using `x` number of points. -- `dragToDraw` (optional): `boolean` - - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modesdraw-circle-by-diameter-mode..ts) - -## DrawEllipseByBoundingBoxMode - -User can draw a new ellipse shape `Polygon` feature by clicking two corners of bounding box. - -### ModeConfig - -The following options can be provided in the `modeConfig` object: - -- `dragToDraw` (optional): `boolean` - - If `true`, user can click and drag instead of clicking twice. Note however, that the user will not be able to pan the map while drawing. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-ellipse-by-bounding-box-mode.ts) - -## DrawEllipseUsingThreePointsMode - -User can draw a new ellipse shape `Polygon` feature by clicking center and two corners of the ellipse. - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/draw-ellipse-using-three-points-mode.ts) - -## SplitPolygonMode - -User can split a polygon by drawing a new `LineString` feature on top of the polygon. - -- If the first and the last click is outside the polygon, it will split the polygon - -- If the clicked position is inside the polygon, it will not split the polygon - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/split-polygon-mode.ts) - -## MeasureDistanceMode - -User can measure a distance between two points. - -The following options can be provided in the `modeConfig` object: - -- `turfOptions` (Object, optional) - - - `options` object passed to turf's [distance](https://turfjs.org/docs/#distance) function - - Default: `undefined` - -- `formatTooltip` (Function, optional) - - - Function to format tooltip text (argument is the numeric distance) - - Default: `(distance) => parseFloat(distance).toFixed(2) + units` - -- `measurementCallback` (Function, optional) - - - Function to call as measurements are calculated - - Default: `undefined` - -- `centerTooltipsOnLine` (Boolean, optional) - - - If true, the measurement tooltips appear on the middle of their respective line segments rather than at the end - - Default: `false` - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-distance-mode.ts) - -## MeasureAreaMode - -User can measure an area by drawing an arbitrary polygon. - -The following options can be provided in the `modeConfig` object: - -- `formatTooltip` (Function, optional) - - - Function to format tooltip text (argument is the numeric area) - - Default: `(distance) => parseFloat(distance).toFixed(2) + units` - -- `measurementCallback` (Function, optional) - - Function to call as measurements are calculated - - Default: `undefined` - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-area-mode.ts) - -## MeasureAngleMode - -User can measure an angle by drawing two lines. - -The following options can be provided in the `modeConfig` object: - -- `formatTooltip` (Function, optional) - - - Function to format tooltip text (argument is the numeric area) - - Default: `(distance) => parseFloat(angle).toFixed(2) + units` - -- `measurementCallback` (Function, optional) - - Function to call as measurements are calculated - - Default: `undefined` - -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/measure-angle-mode.ts) - - -## ElevationMode - -User can move a point up and down. - -The following options can be provided in the `modeConfig` object: - -- `minElevation` (Number, optional) - - - The minimum elevation to allow - - Default: `0` - -- `maxElevation` (Number, optional) - - - The maximum elevation to allow - - Default: `20000` - -- `calculateElevationChange` (Function, optional) - - A function to use to calculate the elevation change in response to mouse movement - - Default: `10 * ` - - Configure to use movement based on viewport: - -```javascript -if (mode === 'elevation') { - modeConfig.calculateElevationChange = (opts) => - ElevationMode.calculateElevationChangeWithViewport(viewport, opts); -} -``` -[Source code](https://github.com/visgl/deck.gl-community/blob/master/modules/editable-layers/src/edit-modes/elevation-mode.ts) - -## Composite Mode - -Use `CompositeMode` to combine multiple modes. -_Not all combinations are guaranteed to work._ - -`new CompositeMode(modes, options = {})` - -- `modes`: `Array` Modes you want to combine. **Order is very important.** -- `options` (optional): Options to be added later. - -``` -new CompositeMode([new DrawLineStringMode(), new ModifyMode()]) -``` - -## Boolean Operations - -For all polygon drawing modes, the following options can be provided in the `modeConfig` object: - -- `booleanOperation` (optional): `null|'union'|'difference'|'intersection'` - - If non-null, requires a single `Polygon` or `MultiPolygon` selection - - If `null`, the drawn `Polygon` is added as a new feature regardless of selection - - If `union`, the drawn `Polygon` is unioned with the selected geometry - - If `difference`, the drawn `Polygon` is subtracted from the selected geometry - - If `intersection`, the drawn `Polygon` is intersected with the selected geometry