# SeaCharts
Python-based API for Electronic Navigational Charts (ENC)
[]()
[]()
[]()
[]()
## Features
- Read and process spatial depth data from
[FileGDB](https://gdal.org/drivers/vector/filegdb.html) files into
shapefiles.
- Access and manipulate standard geometric shapes such as points and polygon
collections.
- Visualize colorful seacharts features and vessels.
## Code style
This module follows the [PEP8](https://www.python.org/dev/peps/pep-0008/)
convention for Python code.
## Roadmap
- 1: Add better compatibility for all operating systems (Windows, Linux++). Right
now, GDAL and Cartopy are problematic to install on most platforms.
Consider finding other packages for map loading and charts projections.
- 2: Add support for multiple map data formats (.gis, .gdb, .json) from any region in
the world, in all UTM zones or lat/lon coordinates.
- 3: Use another plotting framework that has higher refresh rate or is feasible for
real-time (Qt?, React?).
- 4: Add options for plotting trajectories, ships, traffic information/AIS data etc.
on the frontend display.
- 5: Add support for reading and loading in weather data (wind and current
maps++) from a separate module.
## Prerequisites
### Linux (Virtual Environment)
First, ensure that you have the GDAL and GEOS libraries installed, as these are
required in order to successfully install GDAL and Cartopy:
```
sudo apt-get install libgeos-dev libgdal-dev
```
From the root folder, one may then install an editable version of the package as
follows:
```
pip install -e .
```
This should preferably be done inside a virtual environment in order to prevent
Python packaging conflicts.
### Anaconda
Install an edition of the [Anaconda](
https://www.anaconda.com/products/individual-d) package manager, and then create a new
_conda environment_
with [Python 3.11](https://www.python.org/downloads/) or higher using e.g. the
graphical user interface of [PyCharm Professional](
https://www.jetbrains.com/lp/pycharm-anaconda/) as detailed [here](
https://www.jetbrains.com/help/pycharm/conda-support-creating-conda-virtual-environment.html
).
The required data processing libraries for spatial calculations and
visualization may subsequently be installed simply by running the following
commands in the terminal of your chosen environment:
```
conda install -c conda-forge fiona cartopy matplotlib
conda install matplotlib-scalebar cerberys pyyaml
```
### Windows (Pipwin)
First, ensure that [Python 3.11](https://www.python.org/downloads/) or higher
is installed. Next, install all required packages using
[Pipwin](https://pypi.org/project/pipwin/):
```
python -m pip install --upgrade pip
pip install wheel
pip install pipwin
pipwin install numpy
pipwin install gdal
pipwin install fiona
pipwin install shapely
pip install cartopy
pip install pyyaml
pip install cerberus
pip install matplotlib-scalebar
```
Simply copy and paste the entire block above (including the empty line) into
the terminal of your virtual environment, and go get a cup of coffee while it
does its thing.
## Installation
After the necessary dependencies have been correctly installed, the SeaCharts
package may be installed directly through the Python Package Index ([PyPI](
https://pypi.org/
)) by running the following command in the terminal:
```
pip install seacharts
```
or locally inside the SeaCharts root folder as an editable package with `pip install
-e .`
## Usage
This module supports reading and processing `FGDB` files for sea depth data,
such as the Norwegian coastal data set used for demonstration purposes, found
[here](
https://kartkatalog.geonorge.no/metadata/2751aacf-5472-4850-a208-3532a51c529a).
### Downloading regional datasets
To visualize and access coastal data of Norway, follow the above link to download
the `Depth data` (`Sjøkart - Dybdedata`) dataset from the [Norwegian Mapping Authority](
https://kartkatalog.geonorge.no/?organization=Norwegian%20Mapping%20Authority) by adding
it to the Download queue and navigating to the separate
[download page](https://kartkatalog.geonorge.no/nedlasting). Choose one or more
county areas (e.g. `Møre og Romsdal`), and select the
`EUREF89 UTM sone 33, 2d` (`UTM zone 33N`) projection and `FGDB 10.0`
format. Finally, select your appropriate user group and purpose, and click
`Download` to obtain the ZIP file(s).
### Configuration and startup
Unpack the downloaded file(s) and place the extracted `.gdb` in a suitable location,
in which the SeaCharts setup may be configured to search. The current
working directory as well as the relative `data/` and `data/db/` folders are
included by default.
The minimal example below imports the `ENC` class from `seacharts.enc` with the
default configuration found in `seacharts/config.yaml`, and shows the interactive
SeaCharts display. Note that at least one database with spatial data (e.g. `Møre og
Romsdal` from the Norwegian Mapping Authority) is required.
```python
if __name__ == '__main__':
from seacharts.enc import ENC
enc = ENC()
enc.display.show()
```
The `config.yaml` file specifies which file paths to open and which area to load.
The corresponding `config_schema.yaml` specifies how the required setup parameters
must be provided, using `cerberus`.
### API usage and accessing geometric shapes
After the spatial data is parsed into shapefiles during setup, geometric
shapes based on the [Shapely](https://pypi.org/project/Shapely/) library may be
accessed and manipulated through various `ENC` attributes. The seacharts
feature layers are stored in `seabed`, `shore` and `land`.
```python
if __name__ == '__main__':
from seacharts.enc import ENC
# Values set in user-defined 'seacharts.yaml'
# size = 9000, 5062
# center = 44300, 6956450
enc = ENC("seacharts.yaml")
print(enc.seabed[10])
print(enc.shore)
print(enc.land)
enc.display.show()
```
Note how custom settings may be set in a user-defined .yaml-file, if its path is
provided to the ENC during initialization. One may also import and create an
instance of the `seacharts.Config` dataclass, and provide it directly to the ENC.
### Environment visualization
The `ENC.start_display` method is used to show a Matplotlib figure plot of the
loaded sea charts features. Zoom and pan the environment view using the mouse
scroll button, and holding and dragging the plot with left click, respectively.
Dark mode may be toggled using the `d` key, and an optional colorbar showing
the various depth legends may be toggled using the `c` key. Images of the
currently shown display may be saved in various resolutions by pressing
Control + `s`, Shift + `s` or `s`.
## License
This project uses the [MIT](https://choosealicense.com/licenses/mit/) license.
MIT License
Copyright (c) 2021 Simon Blindheim
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://github.com/simbli/seacharts",
"name": "seacharts",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "api,ships,sea charts,visualization,electronic navigational charts",
"author": "Simon Blindheim, Trym Tengesdal",
"author_email": "simon.blindheim@ntnu.no",
"download_url": "https://files.pythonhosted.org/packages/5d/79/08a7f209bb23c2b6de15e260efd6b98d96f62703d82044e728585569b54d/seacharts-3.0.0.tar.gz",
"platform": null,
"description": "# SeaCharts\nPython-based API for Electronic Navigational Charts (ENC)\n\n[]()\n[]()\n[]()\n[]()\n\n![](images/example1.svg\n\"Example visualization with vessels and geometric shapes in dark mode.\")\n\n## Features\n\n- Read and process spatial depth data from\n [FileGDB](https://gdal.org/drivers/vector/filegdb.html) files into\n shapefiles.\n- Access and manipulate standard geometric shapes such as points and polygon\n collections.\n- Visualize colorful seacharts features and vessels.\n\n## Code style\n\nThis module follows the [PEP8](https://www.python.org/dev/peps/pep-0008/)\nconvention for Python code.\n\n## Roadmap\n\n- 1: Add better compatibility for all operating systems (Windows, Linux++). Right\n now, GDAL and Cartopy are problematic to install on most platforms.\n Consider finding other packages for map loading and charts projections.\n- 2: Add support for multiple map data formats (.gis, .gdb, .json) from any region in\n the world, in all UTM zones or lat/lon coordinates.\n- 3: Use another plotting framework that has higher refresh rate or is feasible for\n real-time (Qt?, React?).\n- 4: Add options for plotting trajectories, ships, traffic information/AIS data etc.\n on the frontend display.\n- 5: Add support for reading and loading in weather data (wind and current\n maps++) from a separate module.\n\n\n## Prerequisites\n\n### Linux (Virtual Environment)\n\nFirst, ensure that you have the GDAL and GEOS libraries installed, as these are\nrequired in order to successfully install GDAL and Cartopy:\n```\nsudo apt-get install libgeos-dev libgdal-dev\n```\n\nFrom the root folder, one may then install an editable version of the package as\nfollows:\n```\npip install -e .\n```\n\nThis should preferably be done inside a virtual environment in order to prevent\nPython packaging conflicts.\n\n### Anaconda\n\nInstall an edition of the [Anaconda](\nhttps://www.anaconda.com/products/individual-d) package manager, and then create a new\n_conda environment_\nwith [Python 3.11](https://www.python.org/downloads/) or higher using e.g. the\ngraphical user interface of [PyCharm Professional](\nhttps://www.jetbrains.com/lp/pycharm-anaconda/) as detailed [here](\nhttps://www.jetbrains.com/help/pycharm/conda-support-creating-conda-virtual-environment.html\n).\n\nThe required data processing libraries for spatial calculations and\nvisualization may subsequently be installed simply by running the following\ncommands in the terminal of your chosen environment:\n\n```\nconda install -c conda-forge fiona cartopy matplotlib\nconda install matplotlib-scalebar cerberys pyyaml\n```\n\n### Windows (Pipwin)\n\nFirst, ensure that [Python 3.11](https://www.python.org/downloads/) or higher\nis installed. Next, install all required packages using\n[Pipwin](https://pypi.org/project/pipwin/):\n```\npython -m pip install --upgrade pip\npip install wheel\npip install pipwin\npipwin install numpy\npipwin install gdal\npipwin install fiona\npipwin install shapely\npip install cartopy\npip install pyyaml\npip install cerberus\npip install matplotlib-scalebar\n\n```\n\nSimply copy and paste the entire block above (including the empty line) into\nthe terminal of your virtual environment, and go get a cup of coffee while it\ndoes its thing.\n\n## Installation\n\nAfter the necessary dependencies have been correctly installed, the SeaCharts\npackage may be installed directly through the Python Package Index ([PyPI](\nhttps://pypi.org/\n)) by running the following command in the terminal:\n\n```\npip install seacharts\n```\n\nor locally inside the SeaCharts root folder as an editable package with `pip install\n-e .`\n\n## Usage\n\nThis module supports reading and processing `FGDB` files for sea depth data,\nsuch as the Norwegian coastal data set used for demonstration purposes, found\n[here](\nhttps://kartkatalog.geonorge.no/metadata/2751aacf-5472-4850-a208-3532a51c529a).\n\n### Downloading regional datasets\n\nTo visualize and access coastal data of Norway, follow the above link to download\nthe `Depth data` (`Sj\u00f8kart - Dybdedata`) dataset from the [Norwegian Mapping Authority](\nhttps://kartkatalog.geonorge.no/?organization=Norwegian%20Mapping%20Authority) by adding\nit to the Download queue and navigating to the separate\n[download page](https://kartkatalog.geonorge.no/nedlasting). Choose one or more\ncounty areas (e.g. `M\u00f8re og Romsdal`), and select the\n`EUREF89 UTM sone 33, 2d` (`UTM zone 33N`) projection and `FGDB 10.0`\nformat. Finally, select your appropriate user group and purpose, and click\n`Download` to obtain the ZIP file(s).\n\n### Configuration and startup\n\nUnpack the downloaded file(s) and place the extracted `.gdb` in a suitable location,\nin which the SeaCharts setup may be configured to search. The current\nworking directory as well as the relative `data/` and `data/db/` folders are\nincluded by default.\n\nThe minimal example below imports the `ENC` class from `seacharts.enc` with the\ndefault configuration found in `seacharts/config.yaml`, and shows the interactive\nSeaCharts display. Note that at least one database with spatial data (e.g. `M\u00f8re og\nRomsdal` from the Norwegian Mapping Authority) is required.\n\n```python\nif __name__ == '__main__':\n\n from seacharts.enc import ENC\n\n enc = ENC()\n enc.display.show()\n```\n\nThe `config.yaml` file specifies which file paths to open and which area to load.\nThe corresponding `config_schema.yaml` specifies how the required setup parameters\nmust be provided, using `cerberus`.\n\n\n### API usage and accessing geometric shapes\n\nAfter the spatial data is parsed into shapefiles during setup, geometric\nshapes based on the [Shapely](https://pypi.org/project/Shapely/) library may be\naccessed and manipulated through various `ENC` attributes. The seacharts\nfeature layers are stored in `seabed`, `shore` and `land`.\n\n```python\nif __name__ == '__main__':\n from seacharts.enc import ENC\n\n # Values set in user-defined 'seacharts.yaml'\n # size = 9000, 5062\n # center = 44300, 6956450\n enc = ENC(\"seacharts.yaml\")\n\n print(enc.seabed[10])\n print(enc.shore)\n print(enc.land)\n\n enc.display.show()\n```\n\nNote how custom settings may be set in a user-defined .yaml-file, if its path is\nprovided to the ENC during initialization. One may also import and create an\ninstance of the `seacharts.Config` dataclass, and provide it directly to the ENC.\n\n![](images/example2.svg \"Example visualization of vessels and a\ncolorbar with depth values in light mode.\")\n\n### Environment visualization\nThe `ENC.start_display` method is used to show a Matplotlib figure plot of the\nloaded sea charts features. Zoom and pan the environment view using the mouse\nscroll button, and holding and dragging the plot with left click, respectively.\n\nDark mode may be toggled using the `d` key, and an optional colorbar showing\nthe various depth legends may be toggled using the `c` key. Images of the\ncurrently shown display may be saved in various resolutions by pressing\nControl + `s`, Shift + `s` or `s`.\n\n## License\n\nThis project uses the [MIT](https://choosealicense.com/licenses/mit/) license.\n\nMIT License\n\nCopyright (c) 2021 Simon Blindheim\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
"bugtrack_url": null,
"license": "",
"summary": "Electronic navigational charts (ENCs) processing & visualization",
"version": "3.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/simbli/seacharts/issues",
"Homepage": "https://github.com/simbli/seacharts"
},
"split_keywords": [
"api",
"ships",
"sea charts",
"visualization",
"electronic navigational charts"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cd0648e7e49d067b80d22ddbbe315aa079e6719b3c661536677e55cd898bb6c4",
"md5": "5aed52f6ac293cfd0c847176acf605f5",
"sha256": "dfbdad5c993249b6a122caec8b30af0dd2c20ab9f51027b6617a0014a6742a19"
},
"downloads": -1,
"filename": "seacharts-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5aed52f6ac293cfd0c847176acf605f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 27134,
"upload_time": "2023-11-02T22:47:16",
"upload_time_iso_8601": "2023-11-02T22:47:16.479963Z",
"url": "https://files.pythonhosted.org/packages/cd/06/48e7e49d067b80d22ddbbe315aa079e6719b3c661536677e55cd898bb6c4/seacharts-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5d7908a7f209bb23c2b6de15e260efd6b98d96f62703d82044e728585569b54d",
"md5": "ee80310f6f5e37212236a82a30c26881",
"sha256": "7506a3cf89f32b32cc9ebe2b3a939e5f266048b1bf3f9abb83f8b8e4b2594acd"
},
"downloads": -1,
"filename": "seacharts-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ee80310f6f5e37212236a82a30c26881",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 25847,
"upload_time": "2023-11-02T22:47:18",
"upload_time_iso_8601": "2023-11-02T22:47:18.015643Z",
"url": "https://files.pythonhosted.org/packages/5d/79/08a7f209bb23c2b6de15e260efd6b98d96f62703d82044e728585569b54d/seacharts-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-02 22:47:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "simbli",
"github_project": "seacharts",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "seacharts"
}
JSON
