{
  "id": "measure",
  "label": "Measure",
  "tagline": "Measures lengths, areas and perimeters by clicking on the map.",
  "status": "stable",
  "element": "webmapx-measure-tool",
  "placement": "toolbar",
  "configType": "measure",
  "demoConfig": "config/docs/tools/measure.json",
  "configFragment": null,
  "source": [
    "src/components/webmapx-measure-tool.ts",
    "src/utils/geo-calculations.ts"
  ],
  "tests": [
    "tests/measure-units.test.ts"
  ],
  "related": [
    "truearea",
    "draw",
    "buffer"
  ],
  "sections": {
    "what": "Measure calculates lengths, areas and perimeters from points clicked on the map.\n\nThe measure tool gives up to four results:\n\n- **distance** along a line, per segment, and as a total length.\n- **area** of a shape, once the line is closed into a shape.\n- **perimeter** of that shape, the total length including the closing segment.\n- a **height profile** along the line, if the map has an elevation layer. So a\n  route has a length and a climb.\n\n**The measurements are made on the globe, not on the flat picture.** Every\nprojection of the earth distorts distances and areas when the round earth is\ndrawn on a flat surface such as a computer screen. On a normal web map,\nGreenland looks as big as Africa, and an area read off that picture is wrong by\na factor of 14. The measure tool ignores the projection and calculates distance\nand area directly on the sphere, so a measurement in Svalbard is comparable with\none in Kenya.\n\nThe tool works at any scale, from a back garden to the distance from New York\nto London (5570 km). Press the unit button in the panel to show results in\nmetric (m, km, m², ha, km²) or imperial (ft, mi, sq ft, acres, sq mi). The\nchoice is stored in this browser, so it is still there after a reload.\n\nThe height profile uses a hundred points along the line and is redrawn while\npoints are added. The profile appears by itself when the map has elevation data.\nThere is nothing to switch on.\n\nA measurement can be corrected with undo, and it can be saved to a file. The\nfile holds the shape and all the numbers that were shown, so it can be mailed to\nsomeone, opened in QGIS or another GIS program, or dropped back on a webmapx\nmap. Saving with styling adds a second file with the colors and labels. That\nsecond file is only understood by webmapx. QGIS reads the shape and the numbers\nfrom the GeoJSON file and ignores the style file.\n\nUse a different tool when:\n\n- the area of a feature that is already on the map is wanted: use **True area**.\n- the result should become a layer to style, save and analyse: use **Draw**,\n  then **Analysis**.",
    "use": "1. Open the ruler icon in the toolbar.\n2. Click the map to place the first point.\n3. Click again for each next point. The panel shows each segment length and the\n   total length so far.\n4. Double-click, right-click, or press Escape to finish the line.\n5. To measure an area, click the **first** point again to complete the shape.\n   The **area** appears in the panel, and the total length is now called\n   **perimeter**.\n6. Placed a point in the wrong spot? Press **Undo** to take back one step at a\n   time.\n7. Press **Save** to write the measurement to a file.\n8. Press **m / km** (or **ft / mi**) to change the displayed unit system.\n   Only the readout changes, so switching costs no precision.\n9. If the map has an elevation layer, the height profile appears under the\n   readout and follows every new point.\n10. The measurement stays on the map until it is cleared or a new one is\n    started.\n\nInside a unit system, the unit follows the size of the number, always with three\nsignificant digits: metres for values under a kilometre and kilometres after\nthat, feet for values under a mile and miles after that, then square feet, acres,\nand square miles.\n\nNothing is added to the legend. A measurement is scratch work and disappears\nwhen it is cleared, unless it is saved.\n\n**What undo takes back.** The button, `Ctrl+Z` (`Cmd+Z` on a Mac), `Backspace`\nand `Delete` all do the same thing. The effect depends on the state of the\nmeasurement:\n\n- on a completed shape, undo **opens it again**: the area disappears, perimeter\n  becomes a total length, and the shape is a line again with all its points.\n- on a finished line, undo **reopens the line**, so clicking can go on.\n- otherwise the **last point** is removed, together with the segment length and\n  its part of the total.\n\nCompleting a shape and placing a point are two separate steps, so opening the\nshape again does not also remove the point it was completed on. Press undo again\nfor that. The button greys out when there is nothing left to undo. Typing in a\nsearch box is safe: Backspace there deletes a character, not a point.\n\n**What Save produces.** Save opens the same dialog the legend uses, so the\noptions are familiar: a filename, style on or off, a `.zip` or a plain\n`.geojson`, and coordinate rounding. With style on, Save writes two files,\n`<name>.geojson` and `<name>_style.json`. That pair is what webmapx reads back:\ndrop it on any webmapx map and the measurement returns with its shape, colors,\nnumbered labels, and named attributes. The measurement does not have to be a\nlayer on the map first.\n\n**What is in the file.** The measured shape (a polygon when completed, a line\nwhen not) carries `segment_1` … `segment_N`, `total` (or `perimeter`), `area`\nwhen there is one, and `measured_in` for the units shown at the time. The file\nalso contains one point per segment with its number and length, so the numbered\nlabels come back with the shape.\n\nThe file holds the **drawn** line, not only the clicked points. A long leg\nfollows a great circle, so the saved line is written out as the measured curve.\nAmsterdam to Tokyo comes out as 85 vertices over the Arctic, with its label\nhalfway along that curve.\n\nLengths are always written in **metres** and areas in **square metres**,\nwhatever the panel was showing. A file saying \"17.12\" would be unreadable\nwithout its unit, and rounding to the displayed value would throw away digits.\nThe display unit travels separately, in the style file. The style file is also\nwhat turns `segment_1` back into \"Segment 1\" when the file is dropped on a map.",
    "embed": "The line is drawn by the map engine itself, so the tool needs no source, no\nlayer and no data. Enabling it is the whole configuration.\n\nThe height profile is the one exception: the profile appears only when the map\nhas an elevation (`raster-dem`) layer, which is why the demo config mentioned\nearlier has one.",
    "extend": "The component handles the pointer events, the totals, the panel, and the profile\ngraph. The arithmetic lives separately in `src/utils/geo-calculations.ts`\n(`haversineDistanceCm`, `geodesicAreaM2`, `formatDistance`, `formatArea`) and\nuses no DOM, so it can be tested directly. `tests/measure-units.test.ts` does\nthat.\n\nDistances are held as **integer centimetres**, not floating-point metres, and\n`formatDistance` is the only place that turns them into text. If you add a\nsecond readout elsewhere in the UI, call it instead of rounding yourself.\n\n**Save reuses the save dialog instead of downloading a file itself.** The dialog\nalready offers filename, style, zip-or-plain, and rounding, and it writes the\n`<name>.geojson` + `<name>_style.json` pair that `dropped-layer-builder` reads\nback. A second exporter here would be a second format to keep in sync with the\nimporter. One trap: the dialog moves itself to `document.body` the first time it\nopens, to escape the panel's `backdrop-filter`, so the `@query` for it must be\ncached. An uncached query finds nothing after that, and every Save click after\nthe first does nothing at all.\n\n**Undo is not an undo stack.** Only three actions change a measurement (complete\na shape, finish a line, add a point) and each has an obvious opposite. The\nopposite is derived from the current state. A stack would store the same facts twice and would have\nto be kept in sync.\n\n**Metric and imperial are two separate ladders, not a conversion.** Each one\nchanges unit where its own smaller unit stops being readable: 1000 m, but\n5280 ft. Formatting in metric and then converting would put the switch in the\nwrong place. `threeSignificant` is shared by both, because the number of digits a\nreader can use is a fact about reading, not about the unit."
  },
  "page": "https://webmapx.com/tools/measure.html",
  "webmapxCommit": "f2fc89415cf002a297adc09a455e56df6bb447ff"
}