Utils

Various generally useful classes and methods.

Functions:

display(*imgs, **kwargs)	Display 2D and 3D ndarrays as images with matplotlib.
save_image(filename, *imgs, **kwargs)	Save 2D and 3D ndarrays as images with matplotlib.

Classes:

DotDict	Subclass of dict, with “dot” (attribute) access to keys, a pretty-printed repr, which indents and truncates large containers, and a JSON repr for Jupyter Lab.
DotList	Returns contained dicts as DotDicts (and contained lists as DotLists), soley to allow attribute access past list indexing
Properties(*args)	A wrapper object to construct filter properties by referencing instance attributes.

class DotDict

Subclass of dict, with “dot” (attribute) access to keys, a pretty-printed repr, which indents and truncates large containers, and a JSON repr for Jupyter Lab.

Any dicts stored in DotDict are returned as DotDicts, to allow chained attribute access. Any lists stored in DotDict are returned as DotLists, which return any contained dict items as DotDicts, allowing chained attribute access past list indexing.

The repr() of a DotDict is truncated for readability, but str() is not.

Example

>>> d = DotDict(a=1, b=[{"foo": "bar"}])
>>> d.a
    1
>>> d["a"]
    1
>>> d.b
    [
      {
        'foo': 'bar'
      }
    ]
>>> d.b[0].foo
    'bar'

asdict() → a deep copy of D, where any DotDicts or DotLists contained are converted to plain types.

Raises RuntimeError if the container is recursive (contains itself as a value).

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

Values that are dicts or lists are cast to DotDicts and DotLists.

items()

Equivalent to dict.items. Values that are plain dicts or lists are returned as DotDicts or DotLists.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised. If v is a dict or list, it is returned as a DotDict or DotList.

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty. If v is a dict or list, it is returned as a DotDict or DotList.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

If d is a dict or list, it is returned as a DotDict or DotList.

values()

Equivalent to dict.values. Values that are plain dicts or lists are returned as DotDicts or DotLists.

class DotList

Returns contained dicts as DotDicts (and contained lists as DotLists), soley to allow attribute access past list indexing

aslist() → a deep copy of L, where any DotDicts or DotLists contained are converted to plain types.

Raises RuntimeError if the container is recursive (contains itself as a value).

pop([index]) → item -- remove and return item at index (default last).

If item is a dict or list, it is returned as a DotDict or DotList. Raises IndexError if list is empty or index is out of range.

class Properties(*args)

A wrapper object to construct filter properties by referencing instance attributes.

By referring to any instance attribute, a corresponding property will be created. The instance validates whether the generated property is in the list of property names that this instance was created with.

See Properties Introduction for a more detailed explanation.

Parameters:name (str) – The property names that are allowed, each as a positional parameter.

Examples

>>> p = Properties("modified", "created")
>>> e = p.modified > "2020-01-01"
>>> e = p.deleted > "2020-01-01"  
Traceback (most recent call last):
  ...
AttributeError: 'Properties' object has no attribute 'deleted'
>>>

display(*imgs, **kwargs)

Display 2D and 3D ndarrays as images with matplotlib.

The ndarrays must either be 2D, or 3D with 1 or 3 bands. If they are 3D masked arrays, the mask will be used as an alpha channel.

Unlike matplotlib’s imshow, arrays can be any dtype; internally, each is normalized to the range [0..1].

Parameters:

• *imgs (1 or more ndarrays) – When multiple images are given, each is displayed on its own row by default.
• bands_axis (int, default 0) – Axis which contains bands in each array.
• title (str, or sequence of str; optional) – Title for each image. If a sequence, must be the same length as imgs.
• size (int, default 10) – Length, in inches, to display the longer side of each image.
• robust (bool, default True) – Use the 2nd and 98th percentiles to compute color limits. Otherwise, the minimum and maximum values in each array are used.
• interpolation (str, default "bilinear") –

  Interpolation method for matplotlib to use when scaling images for display.

  Bilinear is the default, since it produces smoother results when scaling down continuously-valued data (i.e. images). For displaying discrete data, however, choose ‘nearest’ to prevent values not existing in the input from appearing in the output.

  Acceptable values are ‘none’, ‘nearest’, ‘bilinear’, ‘bicubic’, ‘spline16’, ‘spline36’, ‘hanning’, ‘hamming’, ‘hermite’, ‘kaiser’, ‘quadric’, ‘catrom’, ‘gaussian’, ‘bessel’, ‘mitchell’, ‘sinc’, ‘lanczos’

• colormap (str, default None) –

  The name of a Colormap registered with matplotlib. Some commonly used built-in options are ‘plasma’, ‘magma’, ‘viridis’, ‘inferno’. See https://matplotlib.org/users/colormaps.html for more options.

  To use a Colormap, the input images must have a single band. The Colormap will be ignored for images with more than one band.

• figsize (tuple(int), default (size, (size / ncols) * nrows)) – Width, height in inches.
• nrows (int, default is the number of images) – Number of rows if there are multiple images.
• ncols (int, default 1) – Number of columns if there are multiple images.
• layout_direction (str, default "left-to-right") – If ncols is greated than 1, it determines whether the layout is left-to-right for the images, or top-to-bottom.

Raises:

ImportError – If matplotlib is not installed.

save_image(filename, *imgs, **kwargs)

Save 2D and 3D ndarrays as images with matplotlib.

For an explanation of the rest of the arguments, please look under display(). For an explanation of valid extension types, please look under matplotlib :func:’savefig’.

Parameters:filename (str) – The name and extension of the image to be saved.