add ImageViz for mapbox ImageSource

[vincentsarago]

This PR tries to add an ImageViz method to enable Mapbox GL static ImageSource.

There is couple things that need to be discussed:

• do we need to pass data here

  mapboxgl-jupyter/mapboxgl/viz.py

  Lines 281 to 290 in 6034cfc

  	class ImageViz(MapViz):
  	"""Create a image viz"""
  	def __init__(self,
  	data,
  	image,
  	coordinates,
  	*args,
  	**kwargs):
  	"""Construct a Mapviz object

• What kind of image input we want to allow ?
• I don't know why but image or coordinates needs to be flipped to be displayed correctly on the map

Preview

cc @dnomadb @ryanbaumann

[dnomadb]

I don't know why but image or coordinates needs to be flipped to be displayed correctly on the map

GL JS explicitly takes the order of UL, UR, LR, LL https://www.mapbox.com/mapbox-gl-js/style-spec#sources-image, not W, S, E, N

What kind of image input we want to allow ?

It seems that this would be most useful for displaying manipulated data, which in most cases would be rows, cols, depth numpy ndarrays.

coordinates = [... ]
img = imread('img.jpg')

visualization = ImageViz(img, coordinates, ...)

visualization.show()

Beyond what this might add in terms of ndarray ==> image data encoding within the library, to be more effectively used we'd probably have to add a utility to take data ndarrays and apply a color ramp (which could be done via `matplotlib):

from matplotlib import cm


# data scaled to 0-1
data

# using the viridis colormap
img = (cm.viridis(data) * np.iiinfo(np.uint8).max).astype(np.uint8)

[ryanbaumann]

This is awesome @vincentsarago! Let me know when you're ready for 👀 on a review.

[dnomadb]

We should use regex to be more robust in catching requests to the Mapbox api -- older styles may still have

• api.tiles.mapbox.com
• a.tiles.mapbox.com
• b.tiles ..

[ryanbaumann]

@dnomadb good flag. I'll include this change in a separate PR, since it spans all visualization types.

[sgillies]

@vincentsarago could we call this class an ImageLayer? it looks layer-like to me and I think Layer could tell a user a lot about how to use the class.

[vincentsarago]

Right now it's a proper MapViz, but I think at the end we could make it a layer meaning that instead of having a ImageViz, we could add a addImage function to the MapViz class.

[ryanbaumann]

Agree, a change to use layer nomenclature makes sense here. I'd propose a renaming of the API from *Viz to *Layer in a separate PR from this one, as a part of #34.

[vincentsarago]

Ok I like the idea of using Matplotlib (+Pillow) if this is what the users are use to do.

Here is what I propose

• add an utility function to encode the image (ndarray) to a base64 string (plus prefix)

# mapboxgl.utils.img_encode

# `img_encode` is a wrapper arround `matplotlib.image.imsave` 
# https://matplotlib.org/api/image_api.html#matplotlib.image.imsave

import base64
from io import BytesIO

def img_encode(arr, **kwargs):
    """Encode ndarray to base64 string image data

    Parameters
    ----------
    arr: ndarray (rows, cols, depth)
    kwargs: passed directly to matplotlib.image.imsave
    """
    sio = BytesIO()
    imsave(sio, arr, **kwargs)
    sio.seek(0)
    img_format = kwargs['format'] if kwargs.get('format') else 'png'
    img_str = base64.b64encode(sio.getvalue()).decode()
    
    return 'data:image/{};base64,{}'.format(img_format, img_str)

• document the use of imread to read image file

img = imread('./mosaic.jpg')
img = np.mean(img[::10, ::10], axis=2)
img = img_encode(img, format='png', cmap='gnuplot')

# Coordinates must be an array in the form of [UL, UR, LR, LL]
coordinates = [
    [-123.40515640309, 38.534294809274336],
    [-115.92938988349292, 38.534294809274336],
    [-115.92938988349292, 32.08296982365502], 
    [-123.40515640309, 32.08296982365502]]

# Create the viz from the dataframe
viz = ImageViz(None, img, coordinates, access_token=token,
                height='400px',
                center = (-119, 35),
                zoom = 5)
viz.show()

@dnomadb @ryanbaumann @sgillies

[ryanbaumann]

@vincentsarago looks great! Made a few comments, all optional. Made a small commit to aid running the example locally for the first time.

[ryanbaumann]

@vincentsarago it may be good to include an optional filename output parameter here. This would encourage users to output a local file with the encoded image data so that the mapboxgl viz class can load the image data asynchronously (versus stick it into a large HTML blob).

[vincentsarago]

In fact I think because mapboxgl can read local files we can totally remove this utility function and show the user it can use imsave

[ryanbaumann]

@vincentsarago let's change this to an async URL load from a local file, if possible, to reduce file size of the notebook and encourage async loading of images.

[vincentsarago]

Oh well I didn't knew mapboxgl could read a local file 👌

[ryanbaumann]

Agree, a change to use layer nomenclature makes sense here. I'd propose a renaming of the API from *Viz to *Layer in a separate PR from this one, as a part of #34.

[ryanbaumann]

@vincentsarago could we simplify the syntax by just passing the pixels or URL for an image to the required data parameter, instead of adding a new parameter?

[vincentsarago]

@ryanbaumann imread comes from matplotlib which is already installed

mapboxgl-jupyter/setup.py

Line 34 in cf08d3e

install_requires=['jinja2', 'geojson', 'colour', 'matplotlib'],

so no need to install imread

[vincentsarago]

same here, numpy will be installed by default when installing mapboxgl-jupyter

[vincentsarago]

ok going back to @dnomadb point earlier, maybe ImageViz could accept 2 kind of input:

• path (string), could be url, local path or event base64 encoded image
• numpy array

If a numpy array is given ImageViz will encode it for the user

cc @ryanbaumann

[vincentsarago]

this is ready @ryanbaumann I'll merge it when the tests will be over !

[ryanbaumann]

🎉 @vincentsarago thanks!