https://github.com/swift502/equimercconverter
Convert images to equirectangular and mercator projections
https://github.com/swift502/equimercconverter
converter equirectangular glsl mercator moderngl projection python
Last synced: about 2 months ago
JSON representation
Convert images to equirectangular and mercator projections
- Host: GitHub
- URL: https://github.com/swift502/equimercconverter
- Owner: swift502
- License: mit
- Created: 2024-02-02T14:25:15.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-28T18:54:02.000Z (6 months ago)
- Last Synced: 2025-10-13T23:32:00.667Z (about 2 months ago)
- Topics: converter, equirectangular, glsl, mercator, moderngl, projection, python
- Language: Python
- Homepage: https://jblaha.art/projects/projection-converter/
- Size: 34.4 MB
- Stars: 18
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Equirectangular-Mercator Projection Converter
Bi-directional image projection converter. Converts images between equirectangular and mercator projections.
Features a fast GPU and a slower CPU conversion implementations:
- The GPU version uses [moderngl](https://github.com/moderngl/moderngl) to transform the image using shaders and then saves it using Pillow
- The CPU version simply uses [Pillow](https://github.com/python-pillow/Pillow) to modify every pixel individually
This project therefore contains working examples of Python and GLSL conversion code. Feel free to borrow them and translate them to your language/project.
## Setup
1. Install [Python 3.11+](https://www.python.org/downloads/)
1. [Clone the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
1. Install requirements
```
pip install -r requirements.txt
```
## Usage
### CLI
```shell
python convert.py path/to/input_image [--to_equirectangular] [--to_mercator] [--nearest] [--cpu]
```
| Parameter | |
| --- | --- |
| ‑‑to_equirectangular | Convert the image to the Equirectangular projection. |
| --to_mercator | Convert the image to the Mercator projection. |
| --nearest | Use nearest sampling for stretching that will occur due to change of aspect ratio. Only used by GPU rendering. |
| --cpu | Use the CPU rendering implementation. Much slower and doesn't support linear sampling. |
#### Examples
```shell
# Merc to equi
python convert.py merc.png --to_equirectangular
# Equi to merc
python convert.py equi.png --to_mercator
```
### Python API
You can use the Converter class directly in Python. Check out the [test script](test.py) to see how to run conversions from code.
## Size limits
Input images have the following size limits:
- GPU (Default)
- To Mercator: 32768 x 16384
- To Equirectangular: 16384 x 32768
- Exceeding these limits will result in `Error: the framebuffer is not complete (INCOMPLETE_ATTACHMENT)`
- CPU (`--cpu`)
- CPU conversion should allow much larger images, but the process is still limited by available system memory. Converting anything above 16384 x 16384 is likely to consume huge amounts of memory. There's also limits imposed by the Pillow library. https://pillow.readthedocs.io/en/stable/reference/limits.html
## Python package
If anyone wants to transform this into a functional, publishable package, feel free to fork the project and publish it. I don't have enough experience doing that and can't imagine many people will use this thing to make the extra effort worthwhile.
## Image sources
- https://en.wikipedia.org/wiki/File:Equirectangular-projection.jpg
- https://en.wikipedia.org/wiki/File:Mercator-projection.jpg