utilities.image_to_url() image parameter has multiple documentation issues #2095
Description
utilities.image_to_url() isn't part of the documented API. However it underlies e.g. ImageLayer. Most of these issues apply there too, but I think these should be resolved first.
def image_to_url(
image: Any,
colormap: Optional[Callable] = None,
origin: str = "upper",
) -> str:
"""
Infers the type of an image argument and transforms it into a URL.
Parameters
----------
image: string, file or array-like object
* If string, it will be written directly in the output file.
* If file, it's content will be converted as embedded in the
output file.
* If array-like, it will be converted to PNG base64 string and
embedded in the output.
...
"""
if isinstance(image, str) and not _is_url(image):
fileformat = os.path.splitext(image)[-1][1:]
with open(image, "rb") as f:
img = f.read()
b64encoded = base64.b64encode(img).decode("utf-8")
url = f"data:image/{fileformat};base64,{b64encoded}"
elif "ndarray" in image.__class__.__name__:
img = write_png(image, origin=origin, colormap=colormap)
b64encoded = base64.b64encode(img).decode("utf-8")
url = f"data:image/png;base64,{b64encoded}"
else:
# Round-trip to ensure a nice formatted json.
url = json.loads(json.dumps(image))
return url.replace("\n", " ")So:
- It isn't documented that a URL
strcan be passed or what the behaviour is. - Mentions of
imagetype 'file' are vague - should be explicit that it must be astrcontaining filepath to an image, so that is is clear that a file object or modernPathlib.pathisn't handled. (The latter can be worked around by wrapping it withstr()- perhaps this should be in the user guide?) - Mention of 'the output file' is incorrect: the function always returns a URL
str.
I propose:
"""
...
Parameters
----------
image: string, or array-like object
* If string is a path to an image file, its content will be converted and embedded in the output URL.
* If string is a URL, it will be linked in the output URL.
* Otherwise a string will be assumed to be JSON and embedded in the output URL.
* If array-like, it will be converted to PNG base64 string and embedded in the output URL.
...
"""folium is maintained by volunteers. Can you help making a fix for this issue?
Yes.