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))¶ Render a
DataArray
timestack (time
,band
,y
,x
) into a GIF.If the
DataArray
contains adask.array.Array
, usedgif
(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 thedate_position
,date_color
, anddate_bg
arguments.- Parameters
arr – Time-stacked array to animate. Must have 3 or 4 dimensions, which are assumed to be in the order
time
, [optionalband
],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
andvmax
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 theDataArray
are not timestamps or timedeltas, you must explicitly passdate_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.
- Returns
If
to
is None, returns anIPython.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: >>> stackstac.gif(arr, date_format="Year: %Y")
>>> # Write the GIF to a file, with no timestamp printed: >>> stackstac.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: >>> stackstac.gif( ... arr.sel(band="ndvi"), cmap="YlGn", date_color=(0, 0, 0), date_bg=None ... )
Dask dgif
¶
-
geogif.
dgif
(arr, *, bytes=False, fps=10, 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))¶ Turn a dask-backed
DataArray
timestack into a GIF, as aDelayed
object.The
DataArray
must have 1 or 3 bands, and dimensions in (time
, [optionalband
],y
,x
) order.If all you want is a GIF,
dgif
can be faster than calling.compute()
and thengif
: 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, usegif
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 thedate_position
,date_color
, anddate_bg
arguments.- Parameters
arr – Time-stacked array to animate. Must have 3 or 4 dimensions, which are assumed to be in the order
time
, [optionalband
],y
,x
.bytes –
Whether to return the GIF as bytes, or as an
IPython.display.Image
. Ifbytes=False
(default), thendgif(...).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
andvmax
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 theDataArray
are not timestamps or timedeltas, you must explicitly passdate_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.
- Returns
Delayed object which, when computed, resolves to either an
IPython.display.Image
, orbytes
.- Return type
dask.Delayed
Examples
>>> # Compute a GIF on the cluster and show it in your notebook: >>> stackstac.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 = stackstac.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 = stackstac.dgif(arr, bytes=True) >>> bucket.setitems({"neat.gif": gif}).compute()