API Reference

Local gif

geogif.gif(arr, *, to=None, fps=16, robust=True, vmin=None, vmax=None, cmap=None, date_format='%Y-%m-%d', date_position='ul', date_color=(255, 255, 255), date_bg=(0, 0, 0), date_size=0.15)

Render a DataArray timestack (time, band, y, x) into a GIF.

If the DataArray contains a dask.array.Array, use dgif (delayed-GIF) instead.

The DataArray must have 1 or 3 bands.

Unless date_format=None, a small timestamp will be printed onto each frame of the animation. You can control the position and styling of this with the date_position, date_color, and date_bg arguments.

Parameters

  • arr – Time-stacked array to animate. Must have 3 or 4 dimensions, which are assumed to be in the order time, [optional band], y, x.

  • to – Where to write the GIF. If None (default), an IPython.display.Image is returned, which will display the GIF in your Jupyter notebook.

  • fps – Frames per second

  • robust – Calculate vmin and vmax from the 2nd and 98th percentiles of the data (default True)

  • vmin – Value in the data to map to 0 (black). If None (default), it’s calculated from the minimum value of the data or the 2nd percentile, depending on robust.

  • vmax – Value in the data to map to 255 (white). If None (default), it’s calculated from the maximum value of the data or the 98nd percentile, depending on robust.

  • cmap –

    Colormap to use for single-band data. Can be a matplotlib colormap name as a string, or a Colormap object for custom colormapping.

    If None (default), the default matplotlib colormap (usually viridis) will automatically be used for 1-band data. Setting a colormap for multi-band data is an error.

  • date_format –

    Date format string (like "%Y-%m-%d", the default) used to format the timestamps written onto each frame of the animation. If the coordinates for axis 0 of the DataArray are not timestamps or timedeltas, you must explicitly pass date_format=None.

    See the Python string format doc for details.

  • date_position – Where to print the timestamp on each frame. One of "ul" (upper-left), "ur" (upper-right), "ll" (lower-left), "lr" (lower-right), default "ul".

  • date_color – Color for the timestamp font, as an RGB 3-tuple. Default: (255, 255, 255) (white).

  • date_bg – Fill color to draw behind the timestamp (for legibility), as an RGB 3-tuple. Default: (0, 0, 0) (black). Set to None to disable.

  • date_size –

    If a float, make the label this fraction of the width of the image. If an int, use this absolute font size for the label. Default: 0.15 (so the label is 15% of the image width).

    Note that if Pillow does not have FreeType support, the font size cannot be adjusted, and the text will be whatever size Pillow’s default basic font is (usually rather small).

Returns

If to is None, returns an IPython.display.Image, which will display the GIF in a Jupyter Notebook. (You can also get the GIF data as bytes from the Image’s .data attribute.)

Otherwise, returns None, and the GIF data is written to to.

Return type

IPython.display.Image or None

Example

>>> # Generate a GIF and show it in your notebook:
>>> geogif.gif(arr, date_format="Year: %Y")

>>> # Write the GIF to a file, with no timestamp printed:
>>> geogif.gif(arr, to="animation.gif", fps=24, date_format=None)

>>> # Show a colormapped GIF of single-band data in your notebook,
>>> # with the timestamp font in black and no background behind it:
>>> geogif.gif(
...     arr.sel(band="ndvi"), cmap="YlGn", date_color=(0, 0, 0), date_bg=None
... )

Dask dgif

geogif.dgif(arr, *, bytes=False, fps=16, robust=True, vmin=None, vmax=None, cmap=None, date_format='%Y-%m-%d', date_position='ul', date_color=(255, 255, 255), date_bg=(0, 0, 0), date_size=0.15)

Turn a dask-backed DataArray timestack into a GIF, as a Delayed object.

The DataArray must have 1 or 3 bands, and dimensions in (time, [optional band], y, x) order.

If all you want is a GIF, dgif can be faster than calling .compute() and then gif: since GIFs are smaller and reduced in quality from NumPy arrays, there’s less data to transfer from the cluster back to your computer. Or, if you want to generate lots of GIFs and store them in a bucket, dgif makes it easier to parallelize that with Dask.

If the DataArray is not delayed, and just contains a NumPy array, use gif instead.

Unless date_format=None, a small timestamp will be printed onto each frame of the animation. You can control the position and styling of this with the date_position, date_color, and date_bg arguments.

Parameters

  • arr – Time-stacked array to animate. Must have 3 or 4 dimensions, which are assumed to be in the order time, [optional band], y, x.

  • bytes –

    Whether to return the GIF as bytes, or as an IPython.display.Image. If bytes=False (default), then dgif(...).compute() will (eventually) display the image in your Jupyter notebook without any extra steps.

    Note that you can also access the raw bytes from an IPython.display.Image with the .data attribute.

  • fps – Frames per second

  • robust – Calculate vmin and vmax from the 2nd and 98th percentiles of the data (default True)

  • vmin – Value in the data to map to 0 (black). If None (default), it’s calculated from the minimum value of the data or the 2nd percentile, depending on robust.

  • vmax – Value in the data to map to 255 (white). If None (default), it’s calculated from the maximum value of the data or the 98nd percentile, depending on robust.

  • cmap –

    Colormap to use for single-band data. Can be a matplotlib colormap name as a string, or a Colormap object for custom colormapping.

    If None (default), the default matplotlib colormap (usually viridis) will automatically be used for 1-band data. Setting a colormap for multi-band data is an error.

  • date_format –

    Date format string (like "%Y-%m-%d", the default) used to format the timestamps written onto each frame of the animation. If the coordinates for axis 0 of the DataArray are not timestamps or timedeltas, you must explicitly pass date_format=None.

    See the Python string format doc for details.

  • date_position – Where to print the timestamp on each frame. One of "ul" (upper-left), "ur" (upper-right), "ll" (lower-left), "lr" (lower-right), default "ul".

  • date_color – Color for the timestamp font, as an RGB 3-tuple. Default: (255, 255, 255) (white).

  • date_bg – Fill color to draw behind the timestamp (for legibility), as an RGB 3-tuple. Default: (0, 0, 0) (black). Set to None to disable.

  • date_size –

    If a float, make the label this fraction of the width of the image. If an int, use this absolute font size for the label. Default: 0.15 (so the label is 15% of the image width).

    Note that if Pillow does not have FreeType support, the font size cannot be adjusted, and the text will be whatever size Pillow’s default basic font is (usually rather small).

Returns

Delayed object which, when computed, resolves to either an IPython.display.Image, or bytes.

Return type

dask.Delayed

Examples

>>> # Compute a GIF on the cluster and show it in your notebook:
>>> geogif.dgif(arr, date_format="Year: %Y").compute()

>>> # Compute a GIF on the cluster, get back the bytes, and write them to a file:
>>> gif_data = geogif.dgif(arr, bytes=True).compute()
>>> with open("animation.gif", "wb") as f:
...     f.write(gif_data)

>>> # Compute a GIF on the cluster, and write it to an S3 bucket:
>>> import fsspec
>>> import dask.delayed
>>> bucket = dask.delayed(fsspec.get_mapper('s3://my-sweet-gifs/latest'))
>>> gif = geogif.dgif(arr, bytes=True)
>>> bucket.setitems({"neat.gif": gif}).compute()