utilities.image_to_url() image parameter has multiple documentation issues

[elliot-100]

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 str can be passed or what the behaviour is.
• Mentions of image type 'file' are vague - should be explicit that it must be a str containing filepath to an image, so that is is clear that a file object or modern Pathlib.path isn't handled. (The latter can be worked around by wrapping it with str() - 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.

[elliot-100]

Raised PR #2106.

[Conengmo]

Thanks for the PR!

Follow up question, since you were looking into this function as well:

        # Round-trip to ensure a nice formatted json.
        url = json.loads(json.dumps(image))

Isn't this weird? What should the functionality be here? I'd not expect a JSON to lead to a valid image url here.