PyramidIO

class toasty.pyramid.PyramidIO(base_dir, scheme='L/Y/YX', default_format=None)

Bases: object

Manage I/O on a tile pyramid.

Parameters:

base_dirstr

The base directory containing the tiles

schemestr

The tile organization scheme, should be either ‘L/Y/YX’ or ‘LXY’

default_formatstr

The file format to assume for the tiles if none is specified when reading/writing tiles. If not specified, and base_dir exists and contains files, these are used to guess default_format. Otherwise defaults to ‘png’.

Notes

If default_format is unspecified, the default guessing process iterates over the pyramid until it finds a file. In a very large pyramid, this can be quite I/O-intensive, so in large tasks you should specify the default explicitly.

Methods Summary

clean_lockfiles(level)	Clean up any lockfiles created during parallelized pyramid creation.
get_default_format()	Get the default image storage format for this pyramid.
get_default_vertical_parity_sign()	Get the parity sign (vertical data layout) of the tiles in this pyramid's default format.
get_path_scheme()	Get the scheme for buiding tile paths as used in the WTML standard.
open_metadata_for_read(basename)	Open a metadata file in read mode.
open_metadata_for_write(basename)	Open a metadata file in write mode.
read_image(pos[, default, masked_mode, format])	Read an Image for the specified tile position.
tile_path(pos[, format, makedirs])	Get the path for a tile, creating its containing directories.
update_image(pos[, default, masked_mode, format])
write_image(pos, image[, format, mode, ...])	Write an Image for the specified tile position.

Methods Documentation

clean_lockfiles(level)

Clean up any lockfiles created during parallelized pyramid creation.

Parameters:

levelint A tile pyramid depth.

Notes

If you use the update_image() method, you should call this function after your processing is complete to remove lockfiles that are created to ensure that multiple processes don’t stomp on each other’s work. The “cascade” stage doesn’t need locking, so in general only the deepest level of the pyramid will need to be cleaned.

get_default_format()

Get the default image storage format for this pyramid.

Returns:

The format, a string resembling "png" or "fits".

get_default_vertical_parity_sign()

Get the parity sign (vertical data layout) of the tiles in this pyramid’s default format.

Returns:

Either +1 or -1, depending on the format.

get_path_scheme()

Get the scheme for buiding tile paths as used in the WTML standard.

Returns:

The naming scheme, a string resembling {1}/{3}/{3}_{2}.

Notes

The naming scheme is currently hardcoded to be the format given above, but in the future other options might become available.

open_metadata_for_read(basename)

Open a metadata file in read mode.

Parameters:

basenamestr

The basename of the metadata file

Returns:

A readable and closeable file-like object returning bytes.

open_metadata_for_write(basename)

Open a metadata file in write mode.

Parameters:

basenamestr

The basename of the metadata file

Returns:

A writable and closeable file-like object accepting bytes.

read_image(pos, default='none', masked_mode=None, format=None)

Read an Image for the specified tile position.

Parameters:

posPos

The tile position to read.

defaultstr, defaults to “none”

What to do if the specified tile file does not exist. If this is “none”, None will be returned instead of an image. If this is “masked”, an all-masked image will be returned, using make_maskable_buffer(). Otherwise, ValueError will be raised.

masked_modetoasty.image.ImageMode

The image data mode to use if default is set to 'masked'.

tile_path(pos, format=None, makedirs=True)

Get the path for a tile, creating its containing directories.

Parameters:

posPos

The tile to get a path for.test_plate_carree_ecliptic

makedirsoptional bool

If True (the default), create containing directories.

Returns:

The path as a string.

Notes

In its default mode this function does I/O itself — it creates the parent directories containing the tile path. It is not an error for the parent directories to already exist. When reading data from a large, existing pyramid, I/O performance might be improved significantly by making sure to set makedirs = False.

update_image(pos, default='none', masked_mode=None, format=None)

write_image(pos, image, format=None, mode=None, min_value=None, max_value=None)

Write an Image for the specified tile position.

Parameters:

posPos

The tile position to write.

imagetoasty.image.Image

The image to write.

formatstr or None (the default)

The format name; one of SUPPORTED_FORMATS

modetoasty.image.ImageMode or None (the default)

The image data mode to use if format is a PIL_FORMATS

min_valuenumber or None (the default)

An optional number only used for FITS images. The value represents to the lowest data value in this image and its children. If not set, the minimum value will be extracted from this image.

max_valuenumber or None (the default)

An optional number only used for FITS images. The value represents to the highest data value in this image and its children. If not set, the maximum value will be extracted from this image.