geovisio/blurring repository overview

GeoVisio is a complete solution for storing and serving your own 📍📷 geolocated pictures (like StreetView⁠ / Mapillary⁠).

➡️ Give it a try at panoramax.ign.fr⁠ or geovisio.fr⁠ !

⁠📦 Components

GeoVisio is modular and made of several components, each of them standardized and ♻️ replaceable.

All of them are 📖 open-source and available online:

⁠🪄🫥 GeoVisio Blurring API

This repository only contains the blurring algorithms and its API.

⁠Install

⁠System dependencies

Some algorithms (compromise and qualitative) will need system dependencies :

• ffmpeg
• libsm6
• libxext6

You can install them through your package manager, for example in Ubuntu:

sudo apt install ffmpeg libsm6 libxext6

⁠Retrieve code

You can download code from this repository with git clone:

git clone https://gitlab.com/geovisio/blurring.git
cd blurring/

⁠Other dependencies

We use Git Submodules⁠ to manage some of our dependencies. Run the following command to get these dependencies:

git submodule update --init

We also use Pip to handle Python dependencies. You can create a virtual environment first:

python -m venv env
source ./env/bin/activate

And depending on if you want to use API, command-line scripts or both, run these commands:

pip install -r requirements-bin.txt  # For CLI
pip install -r requirements-api.txt  # For API

If at some point you're lost or need help, you can contact us through issues⁠ or by email⁠.

⁠Usage

⁠Command-line interface

All details of available commands are listed in USAGE.md⁠ documentation, or by calling this command:

python src/main.py --help

A single picture can be blurred using the following command:

python src/main.py <path the the picture> <path to the output picture>

You can also launch the CLI through Docker:

docker run \
	geovisio/blurring \
	cli

⁠Web API

The Web API can be launched with the following command:

uvicorn src.api:app --reload

It is then accessible on localhost:8000⁠.

You can also launch the API through Docker:

docker run \
	-p 8000:80 \
	--name geovisio_blurring \
	geovisio/blurring \
	api

API documentation is available under /docs route, so localhost:8000/docs⁠ if you use local instance.

A single picture can be blurred using the following HTTP call (here made using curl):

# Considering your picture is called my_picture.jpg
curl -X 'POST' \
  'http://127.0.0.1:8000/blur/' \
  -H 'accept: image/webp' \
  -H 'Content-Type: multipart/form-data' \
  -F 'picture=@my_picture.jpg;type=image/jpeg' \
  --output blurred.webp

Note that various settings can be changed to control API behaviour. You can edit them using one of the described method in FastAPI documentation⁠. Available settings are:

• STRATEGY: blur algorithm to use (FAST, LEGACY, COMPROMISE, QUALITATIVE)
• WEBP_METHOD: quality/speed trade-off for WebP encoding of pictures derivates (0=fast, 6=slower-better, 6 by default)

⁠Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

You might want to read more about available blur algorithms⁠.

⁠Testing

Tests are handled with Pytest. You can run them using:

pip install -r requirements-dev.txt
pytest

⁠Documentation

High-level documentation for command-line script is handled by Typer⁠. You can update the generated USAGE.md file using this command:

make docs

⁠🤗 Special thanks

GeoVisio was made possible thanks to a group of ✨ amazing people ✨ :

• GéoVélo⁠ team, for 💶 funding initial development and for 🔍 testing/improving software
• Carto Cité⁠ team (in particular Antoine Riche), for 💶 funding improvements on viewer (map browser, flat pictures support)
• La Fabrique des Géocommuns (IGN)⁠ for offering long-term support and funding the Panoramax⁠ initiative and core team (Camille Salou, Mathilde Ferrey, Christian Quest, Antoine Desbordes, Jean Andreani, Adrien Pavie)
• Many many wonderful people who worked on various parts of GeoVisio or core dependencies we use : 🧙 Stéphane Péneau, 🎚 Albin Calais & Cyrille Giquello, 📷 Damien Sorel⁠, Pascal Rhod, Nick Whitelegg...
• Adrien Pavie⁠, for ⚙️ initial development of GeoVisio
• And you all ✨ GeoVisio users for making this project useful !

⁠⚖️ License

Copyright (c) GeoVisio team 2022-2023, released under MIT license⁠.