{
  "id": "cartogram",
  "label": "Cartogram",
  "tagline": "Resizes regions by a numeric value.",
  "status": "stable",
  "element": "webmapx-cartogram-tool",
  "placement": "toolbar",
  "configType": "cartogram",
  "demoConfig": "config/docs/tools/cartogram.json",
  "configFragment": null,
  "source": [
    "src/components/webmapx-cartogram-tool.ts",
    "src/utils/cartogram.ts",
    "src/utils/geoprocessing-operations.ts"
  ],
  "tests": [
    "tests/cartogram.test.ts"
  ],
  "related": [
    "geoprocessing",
    "projection",
    "truearea"
  ],
  "sections": {
    "what": "A cartogram sizes each region by a value instead of by its real area. Choose a\npopulation column and countries with more people take up more room.\n\nThe whole layer keeps roughly the same overall size. The distribution changes,\nnot the frame of the map.\n\nAreas are measured on the sphere in square metres. This avoids using Mercator\nscreen area, where high-latitude regions start too large.\n\nFive methods are available:\n\n- **keep the map joined up, exact areas** (default): neighbors stay attached\n  and areas land within a percent or two.\n- **keep the map joined up (classic, faster)**: Dougenik–Chrisman–Niemeyer.\n  Quicker and rougher. The **Detail** slider controls how many passes it gets.\n- **keep the map joined up, exact areas (go-cart Wasm)**: Gastner–Newman\n  diffusion, the Worldmapper method.\n- **resize each shape in place**: every outline is kept exactly, and gaps\n  open between neighbors.\n- **replace each by a circle (Dorling)**: shapes are replaced by circles.\n\nUse something else when the question is \"how big is this really?\" rather than\n\"how big is this value.\" That is **True area**, or a switch to an equal-area\nprojection with the **Projection** tool.\n\nThe demo map opens in Equal Earth, not Web Mercator. The projection tool is on\nthe toolbar so you can compare the same result in Mercator.",
    "use": "1. Open the cartogram icon in the toolbar.\n2. Pick the **input layer**. Any polygon layer on the map can be used.\n3. Pick the attribute to **size by**. Only attributes observed to hold numbers\n   are offered. Features without a positive value are left out.\n4. Pick a **cartogram type**. Start with the default.\n5. Optionally raise **leave out anything below**: a region asked to shrink ten\n   thousandfold cannot get there and can distort the rest of the map.\n6. Press **Calculate**. The elapsed time is shown while it runs and the run can\n   be canceled. A world layer takes a few seconds.\n7. The result arrives as a new layer in the legend, with the original still\n   underneath. That comparison is the point of the result.\n\n**Only drawn data is used.** For a layer served as vector tiles, only the\nfeatures in view take part, and the panel says so. Zoom out until the whole\nlayer is on screen before calculating, or use a layer with a `geojson` source,\nwhere the full dataset is always available.\n\n**[Worked example](./analysis-single-layer.html#cartogram)**: the same five\ncountries sized by `pop_est`, generated by running the operation rather than\ndrawn by hand.\n\n**Polygons only.** A cartogram sizes a shape by its area, and a point or a line\nhas none, so the operation refuses those rather than guessing. See the\n**[geometry matrix](./analysis-geometry.html#geometry-support)**.",
    "embed": "The tool works on an ordinary polygon layer that carries a numeric attribute.\nThere is no special layer type and no preparation step. The demo config points\nat Natural Earth country polygons with a `pop_est` column.",
    "extend": "`webmapx-cartogram-tool` subclasses the geoprocessing tool with one operation\npinned. Use the same pattern to give another analysis operation its own toolbar\nbutton: subclass, set `pinnedOperation`, add a registry entry.\n\nThe maths is a plain GeoJSON→GeoJSON function in `src/utils/cartogram.ts`, wired\nin as the operation's `compute`. The function undoes the pipeline's Web Mercator\nround trip itself, because the pipeline hands every operation EPSG:3857 and\nMercator inflates area by 1/cos²(latitude).\n\nThree rules are important: grow each part of a multipart feature around **that\npart's own center**, take longitude steps **the short way** round the globe, and\n**measure and correct** the achieved area over up to four passes."
  },
  "page": "https://webmapx.com/tools/cartogram.html",
  "webmapxCommit": "f2fc89415cf002a297adc09a455e56df6bb447ff"
}