npm package: @sean_kenny/coloured-bitmap-to-geojson-polygons-js
Description: A library for convering colour segmented bitmaps to a GeoJSON file of polygons.
Author: Sean Kenny
Latest version: 0.4.0

# coloured-bitmap-to-geojson-js

This is a TypeScript library which contains a function which converts `.bmp` bitmap files into a GeoJSON file.

[![Version](https://img.shields.io/npm/v/@sean_kenny/coloured-bitmap-to-geojson-polygons-js.svg)](https://www.npmjs.com/package/@sean_kenny/coloured-bitmap-to-geojson-polygons-js)
[![Downloads/week](https://img.shields.io/npm/dw/@sean_kenny/coloured-bitmap-to-geojson-polygons-js.svg)](https://www.npmjs.com/package/@sean_kenny/coloured-bitmap-to-geojson-polygons-js)

## Installation and Usage

```
$ npm install --save-dev @sean_kenny/coloured-bitmap-to-geojson-polygons-js
# or
$ yarn add -D @sean_kenny/coloured-bitmap-to-geojson-polygons-js
```

An output can then be generated by calling the `exportColouredBitmapToGeoJSONPolygons` function, which is the only function in the library. `colourToPropertiesMap` is an argument which can be used to attach properties (besides `colourHexCode`) to regions in your bitmap of a particular colour. Keys in `colourToPropertiesMap` must be lowercase (Ex. `ff0000` rather than `FF0000`).
```
const { outputGeoJSON, bmpFileMetadata } = await exportColouredBitmapToGeoJSONPolygons({
  inputFilePath: '/path/to/your/file/your_file.bmp',
  colourToPropertiesMap: {
    "#ff0000": {
      zone: "The red zone"
    },
    "#00ff00": {
      zone: "The green zone"
    },
  }
})
```
`bmpFileMetadata` will contain some data in the following format:
```
{
  "header": {
    "signature": "BM",
    "fileSizeBytes": 120054,
    "reservedField": "00000000",
    "dataOffsetBytes": 54
  },
  "infoHeader": {
    "bitsPerPixel": "TWENTY_FOUR_BIT_RGB",
    "bmpHeightPx": 200,
    "bmpWidthPx": 200,
    "compressionType": "BI_RGB",
    "horizontalPixelsPerMetre": 0,
    "imageCompressedSizeBytes": 0,
    "infoHeaderSizeBytes": 40,
    "numberOfColoursUsed": 0,
    "numberOfImportantColours": 0,
    "numberOfPlanes": 1,
    "verticalPixelsPerMetre": 0
  },
  "colourMap": {}
}
```
And `outputGeoJSON` will contain some data in the following format:
```
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-180, 90],
            [-180, -90],
            ...
          ]
        ]
      },
      "properties": {
        "colourHexCode": "#ff0000",
        "data": { "zone": "The red zone" }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-176.4, 90],
            [-176.4, 89.1],
            ...
          ]
        ]
      },
      "properties": {
        "colourHexCode": "#00ff00",
        "data": { "zone": "The green zone" }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [1.8000000000000114, 1.7999999999999972],
            [1.8000000000000114, 0],
            ...
          ]
        ]
      },
      "properties": {
        "colourHexCode": "#0000ff",
        "data": null
      }
    }
  ]
}
```

### domainBounds 

`domainBounds` is an additional optional argument to `exportColouredBitmapToGeoJSONPolygons` which allows you to specify where the corners of your output GeoJSON file should be on the globe. The default `domainBounds` values is `{ latitudeLowerBound: -90, latitudeUpperBound: 90, longitudeLowerBound: -180, longitudeUpperBound: 180 }` which covers the entire globe. The image below shows the effect of a `domainBounds` value of `{ domainLatitudeLowerBound: -30, domainLatitudeUpperBound: 60, domainLongitudeLowerBound: -20, domainLongitudeUpperBound: 20}` on a `.bmp` file.

Original BMP file          |  Output GeoJSON file
:-------------------------:|:-------------------------:
![](https://github.com/SeanKennyNF/coloured-bitmap-to-geojson-polygons-js/blob/main/readme-images/domain-bounds-example.png)  |  ![](https://github.com/SeanKennyNF/coloured-bitmap-to-geojson-polygons-js/blob/main/readme-images/domain-bounds-example-output.png)


## Some sample inputs and outputs

Original BMP file          |  Output GeoJSON file
:-------------------------:|:-------------------------:
![](https://github.com/SeanKennyNF/coloured-bitmap-to-geojson-polygons-js/blob/main/readme-images/bmp-24.png)  |  ![](https://github.com/SeanKennyNF/coloured-bitmap-to-geojson-polygons-js/blob/main/readme-images/bmp-24-output.png)
![](https://github.com/SeanKennyNF/coloured-bitmap-to-geojson-polygons-js/blob/main/readme-images/provinces-subset-2.png)  |  ![](https://github.com/SeanKennyNF/coloured-bitmap-to-geojson-polygons-js/blob/main/readme-images/provinces-subset-2-output.png)

## Acknowledgements

There's some interesting reading about the exact structure of a bitmap file [here](https://en.wikipedia.org/wiki/BMP_file_format) which is what a lot of this library is based on.

All files whose name follows the pattern `provinces-XXXXXXX.bmp` which are used for testing are pulled directly from the `ab937cf899b75f74662a17574bd0d46072793beb` version of [Anbennar](https://bitbucket.org/JayBean/anbennar-eu4-fork-public-build) which was published to Bitbucket on August 23rd 2024. All credit for those bitmaps goes to their creator. ``bmp-24.bmp` was generously made public by the [University of South Carolina]('https://people.math.sc.edu/Burkardt/data/bmp/bmp.html').

You're welcome to use this library for anything you'd like. Please keep in mind this hasn't been thoroughly tested with a large variety of bitmap files so this may or may not work for your use case. Please reach out if you have a bitmap file which is not processed properly by this library and I'd be happy to work on something to make it work for you.