python-visualization / python-visualization/branca

Is it normal for `branca.utilities.write_png` function to normalize its values?

Open
#195 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
134
Forks
69
Avg merge
1h 10m
Merged PRs (30d)
1

Description

I may be wrong, but I find it weird the way branca.utilities.write_png function normalize its values.
See https://github.com/python-visualization/branca/blob/v0.8.1/branca/utilities.py#L324.

>>> import io
>>>
>>> import numpy as np
>>> import PIL.Image
>>>
>>> import branca.utilities
>>>
>>> data = np.array([[[0.74901961, 0.50196078, 1.0, 1.0], [0.25098039, 1.0, 0.74901961, 1.0]]])
>>>
>>> # Current result
>>> png_bytes = branca.utilities.write_png(data)
>>> with PIL.Image.open(io.BytesIO(png_bytes)) as image:
...     np.asarray(image)
array([[[255, 127, 255, 255],
        [ 85, 255, 191, 255]]], dtype=uint8)
>>>
>>> # What I expected
>>> np.rint(data * 255.0).astype(np.uint8)
array([[[191, 128, 255, 255],
        [ 64, 255, 191, 255]]], dtype=uint8)

As a result, folium layers like folium.raster_layers.ImageOverlay appear brighter than I expected when passing image as an array because of the normalization.
I guess this allows users to automatically display mono rasters with a scale from minimum value as black to maximum value as white. However, for non-mono and mono rasters with a colormap, the normalization seems undesirable.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in branca/utilities.py at write_png, using the linked line and the supplied NumPy/PIL example to reproduce the current output. Done means deciding and verifying the intended normalization behavior for mono, non-mono, and colormapped rasters, including the reported brightness effect in folium ImageOverlay layers.

Written by the indexing model from the issue text.

Assessment

Tech stack
numpy, python
Domain
data-visualization
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.