Footprint

class buzzard.Footprint(**kwargs)[source]

Immutable object representing the location and size of a spatially localized raster. All methods are thread-safe.

The Footprint class:

  • is a toolbox class designed to position a rectangle in both image space and geometry space,

  • can be seen as a shapely.geometry.Polygon rectangle that also defines a grid of pixels,

  • its main purpose is to simplify the manipulation of windows in rasters,

  • has many accessors,

  • has many algorithms,

  • is a constant object,

  • is designed to work with any rectangle in space (like non north-up/west-left rasters),

  • is independent from projections, units and files,

  • uses affine library internally for conversions (https://github.com/sgillies/affine).

Warning

This class being complex and full python, the constructor is too slow for certain use cases (~0.5ms).

Method category

Method names

Footprint construction

from scratch

__init__, of_extent

from Footprint

__and__, intersection, erode, dilate, …

Conversion

extent, coords, geom, __geo_interface__

Accessors

Spatial - Size and vectors

size, width, height, diagvec, …

Spatial - Coordinates

tl, bl, br, tr, …

Spatial - Misc

area, length, semiminoraxis, …

Raster - Size

rsize, rwidth, rheight, …

Raster - Indices

rtl, rbl, rbr, ttr, …

Raster - Misc

rarea, rlength, rsemiminoraxis, …

Affine transformations

pxsize, pxvec, angle, …

Binary predicates

__eq__, …

Numpy

shape, meshgrid_raster, meshgrid_spatial, slice_in, …

Coordinates conversions

spatial_to_raster, raster_to_spatial

Geometry / Raster conversions

find_polygons, burn_polygons, …

Tiling

tile, tile_count, tile_occurrence

Serialization

__str__, …

Informations on geo transforms (gt) and affine matrices

GDAL ordering:

c

a

b

f

d

e

tlx

width of a pixel

row rotation

tly

column rotation

height of a pixel

>>> c, a, b, f, d, e = fp.gt
>>> tlx, dx, rx, tly, ry, dy = fp.gt

Matrix ordering:

a

b

c

d

e

f

width of a pixel

row rotation

tlx

column rotation

height of a pixel

tly

>>> a, b, c, d, e, f = fp.aff6
>>> dx, rx, tlx, ry, dy, tly = fp.aff6

There are only two ways to construct a Footprint, but several high level constructors exist, such as .intersection.

Usage 1

>>> buzz.Footprint(tl=(0, 10), size=(10, 10), rsize=(100, 100))

Usage 2

>>> buzz.Footprint(gt=(0, .1, 0, 10, 0, -.1), rsize=(100, 100))

Parameters

tl: (nbr, nbr)

raster spatial top left coordinates

gt: (nbr, nbr, nbr, nbr, nbr, nbr)

geotransforms with GDAL ordering

size: (nbr, nbr)

Size of Footprint in space (unsigned)

rsize: (int, int)

Size of raster in pixel (unsigned integers)

__and__(other)[source]

Returns Footprint.intersection

classmethod of_extent(extent, scale)[source]

Create a Footprint from a rectangle extent and a scale

Parameters

extent: (nbr, nbr, nbr, nbr)

Spatial coordinates of (minx, maxx, miny, maxy) defining a rectangle

scale: nbr or (nbr, nbr)

Resolution of output Footprint:

  • if nbr: resolution = [a, -a]

  • if (nbr, nbr): resolution [a, b]

clip(startx, starty, endx, endy)[source]

Construct a new Footprint by clipping self using pixel indices

To clip using coordinates see Footprint.intersection.

Parameters

startx: int or None

Same rules as regular python slicing

starty: int or None

Same rules as regular python slicing

endx: int or None

Same rules as regular python slicing

endy: int or None

Same rules as regular python slicing

Returns

fp: Footprint

The new clipped Footprint

erode(self, inward_count, /)[source]
erode(self, inward_count_x, inward_count_y, /) None
erode(self, inward_count_left, inward_count_right, inward_count_top, inward_count_bottom, /) None

Erode self’s edges by the given pixel count to construct a new Footprint.

A negative erosion is a dilation.

Parameters

args: int or (int, int) or (int, int, int, int)

When int, erode all 4 directions by that much pixels When (int, int), erode x and y by a different number of pixel When (int, int, int, int), erode all 4 directions with a different number of pixel

Returns

Footprint

dilate(self, outward_count, /)[source]
dilate(self, outward_count_x, outward_count_y, /) None
dilate(self, outward_count_left, outward_count_right, outward_count_top, outward_count_bottom, /) None

Dilate self’s edges by the given pixel count to construct a new Footprint.

A negative dilation is an erosion.

Parameters

args: int or (int, int) or (int, int, int, int)

When int, dilate all 4 directions by that much pixels When (int, int), dilate x and y by a different number of pixel When (int, int, int, int), dilate all 4 directions with a different number of pixel

Returns

Footprint

intersection(self, *objects, scale='self', rotation='auto', alignment='auto', homogeneous=False)[source]

Construct a Footprint bounding the intersection of geometric objects, self being one of the of input geometry. Inputs’ intersection is always within output Footprint.

Parameters

objects: object

Any object with a __geo_interface__ attribute defining a geometry, like a Footprint or a shapely object.

scale: one of {‘self’, ‘highest’, ‘lowest’} or (nbr, nbr) or nbr

‘self’: Output Footprint’s resolution is the same as self ‘highest’: Output Footprint’s resolution is the highest one among the input Footprints ‘lowest’: Output Footprint’s resolution is the lowest one among the input Footprints (nbr, nbr): Signed pixel size, aka scale nbr: Signed pixel width. Signed pixel height is assumed to be -width

rotation: one of {‘auto’, ‘fit’} or nbr
‘auto’

If scale designate a Footprint object, its rotation is chosen Else, self’s rotation is chosen

‘fit’

Output Footprint is the rotated minimum bounding rectangle

nbr

Angle in degree

alignment: {‘auto’, ‘tl’, (nbr, nbr)}
‘auto’:
  • If scale and rotation designate the same Footprint object, its alignment

    is chosen

  • Else, ‘tl’ alignment is chosen

‘tl’: Ouput Footprint’s alignement is the top left most point of the bounding rectangle

of the intersection

(nbr, nbr): Coordinate of a point that lie on the grid.

This point can be anywhere in space.

homogeneous: bool

False: No effect True: Raise an exception if all input Footprints do not lie on the same grid as self.

Returns

Footprint

move(tl, tr=None, br=None, round_coordinates=False)[source]

Create a copy of self moved by an Affine transformation by providing new points. rsize is always conserved

Usage cases

tl

tr

br

Affine transformations possible

coord

None

None

Translation

coord

coord

None

Translation, Rotation, Scale x and y uniformly with positive real

coord

coord

coord

Translation, Rotation, Scale x and y independently with reals

Parameters

tl: (nbr, nbr)

New top left coordinates

tr: (nbr, nbr)

New top right coordinates

br: (nbr, nbr)

New bottom right coordinates

round_coordinates: bool

Round the input coordinates with respect to buzz.env.significant, so that the output Footprint is as much similar as possible as the input Footprint regarding those properties: - angle - pxsize - pxsizex / pxsizey

This option helps a lot if the input coordinates suffered from floating point precision loss since it will cancel the noise in the resulting transformation matrix.

Warning

Only work when tr and br are both provided

Returns

Footprint

property extent

Get the Footprint’s extent (x then y)

Example

>>> minx, maxx, miny, maxy = fp.extent
>>> plt.imshow(arr, extent=fp.extent)

fp.extent from fp.bounds using numpy fancy indexing

>>> minx, maxx, miny, maxy = fp.bounds[[0, 2, 1, 3]]
property bounds

Get the Footprint’s bounds (min then max)

Example

>>> minx, miny, maxx, maxy = fp.bounds

fp.bounds from fp.extent using numpy fancy indexing

>>> minx, miny, maxx, maxy = fp.extent[[0, 2, 1, 3]]
property coords

Get corners coordinates

Example

>>> tl, bl, br, tr = fp.coords
property poly

Convert self to shapely.geometry.Polygon

property __geo_interface__
property size

(||raster left - raster right||, ||raster top - raster bottom||)

Type:

Spatial distances

property sizex

||raster left - raster right||

Type:

Spatial distance

property sizey

||raster top - raster bottom||

Type:

Spatial distance

property width

||raster left - raster right||, alias for sizex

Type:

Spatial distance

property height

||raster top - raster bottom||, alias for sizey

Type:

Spatial distance

property w

||raster left - raster right||, alias for sizex

Type:

Spatial distance

property h

||raster top - raster bottom||, alias for sizey

Type:

Spatial distance

property lrvec

(raster right - raster left)

Type:

Spatial vector

property tbvec

(raster bottom - raster top)

Type:

Spatial vector

property diagvec

(raster bottom right - raster top left)

Type:

Spatial vector

property tl

raster top left (x, y)

Type:

Spatial coordinates

property tlx

raster top left (x)

Type:

Spatial coordinate

property tly

raster top left (y)

Type:

Spatial coordinate

property bl

raster bottom left (x, y)

Type:

Spatial coordinates

property blx

raster bottom left (x)

Type:

Spatial coordinate

property bly

raster bottom left (y)

Type:

Spatial coordinate

property br

raster bottom right (x, y)

Type:

Spatial coordinates

property brx

raster bottom right (x)

Type:

Spatial coordinate

property bry

raster bottom right (y)

Type:

Spatial coordinate

property tr

raster top right (x, y)

Type:

Spatial coordinates

property trx

raster top right (x)

Type:

Spatial coordinate

property try_

raster top right (y) Don’t forget the trailing underscore

Type:

Spatial coordinate

property t

raster top center (x, y)

Type:

Spatial coordinates

property tx

raster top center (x)

Type:

Spatial coordinate

property ty

raster top center (y)

Type:

Spatial coordinate

property l

raster center left (x, y)

Type:

Spatial coordinates

property lx

raster center left (x)

Type:

Spatial coordinate

property ly

raster center left (y)

Type:

Spatial coordinate

property b

raster bottom center (x, y)

Type:

Spatial coordinates

property bx

raster bottom center (x)

Type:

Spatial coordinate

property by

raster bottom center (y)

Type:

Spatial coordinate

property r

raster center right (x, y)

Type:

Spatial coordinates

property rx

raster center right (x)

Type:

Spatial coordinate

property ry

raster center right (y)

Type:

Spatial coordinate

property c

raster center (x, y)

Type:

Spatial coordinates

property cx

raster center (x)

Type:

Spatial coordinate

property cy

raster center (y)

Type:

Spatial coordinate

property semiminoraxis

half-size of the smaller side

Type:

Spatial distance

property semimajoraxis

half-size of the bigger side

Type:

Spatial distance

property area

pixel count

Type:

Area

property length

circumference of the outer ring

Type:

Length

property rsize

(pixel per line, pixel per column)

Type:

Pixel quantities

property rsizex

pixel per line

Type:

Pixel quantity

property rsizey

pixel per column

Type:

Pixel quantity

property rwidth

pixel per line, alias for rsizex

Type:

Pixel quantity

property rheight

pixel per column, alias for rsizey

Type:

Pixel quantity

property rw

pixel per line, alias for rsizex

Type:

Pixel quantity

property rh

pixel per column, alias for rsizey

Type:

Pixel quantity

property rtl

raster top left pixel (x=0, y=0)

Type:

Indices

property rtlx

raster top left pixel (x=0)

Type:

Index

property rtly

raster top left pixel (y=0)

Type:

Index

property rbl

raster bottom left pixel (x=0, y)

Type:

Indices

property rblx

raster bottom left pixel (x=0)

Type:

Index

property rbly

raster bottom left pixel (y)

Type:

Index

property rbr

raster bottom right pixel (x, y)

Type:

Indices

property rbrx

raster bottom right pixel (x)

Type:

Index

property rbry

raster bottom right pixel (y)

Type:

Index

property rtr

raster top right pixel (x, y=0)

Type:

Indices

property rtrx

raster top right pixel (x)

Type:

Index

property rtry

raster top right pixel (y=0)

Type:

Index

property rt

raster top center pixel (x truncated, y=0)

Type:

Indices

property rtx

raster top center pixel (x truncated)

Type:

Index

property rty

raster top center pixel (y=0)

Type:

Index

property rl

raster center left pixel (x=0, y truncated)

Type:

Indices

property rlx

raster center left pixel (x=0)

Type:

Index

property rly

raster center left pixel (y truncated)

Type:

Index

property rb

raster bottom center pixel (x truncated, y)

Type:

Indices

property rbx

raster bottom center pixel (x truncated)

Type:

Index

property rby

raster bottom center pixel (y)

Type:

Index

property rr

raster center right pixel (x, y truncated)

Type:

Indices

property rrx

raster center right pixel (x)

Type:

Index

property rry

raster center right pixel (y truncated)

Type:

Index

property rc

raster center pixel (x truncated, y truncated)

Type:

Indices

property rcx

raster center pixel (x truncated)

Type:

Index

property rcy

raster center pixel (y truncated)

Type:

Index

property rsemiminoraxis

half pixel count (truncated) of the smaller side

Type:

Pixel quantity

property rsemimajoraxis

half pixel count (truncated) of the bigger side

Type:

Pixel quantity

property rarea

pixel count

Type:

Pixel quantity

property rlength

pixel count in the outer ring

Type:

Pixel quantity

property gt

First 6 numbers of the affine transformation matrix, GDAL ordering

property aff33

The affine transformation matrix

property aff23

Top two rows of the affine transformation matrix

property aff6

First 6 numbers of the affine transformation matrix, left-right/top-bottom ordering

property affine

Underlying affine object

property scale

scale used in the affine transformation, np.abs(scale) == pxsize

Type:

Spatial vector

property angle

rotation used in the affine transformation, (0 is north-up)

Type:

Angle in degree

property pxsize

||pixel bottom right - pixel top left|| (x, y)

Type:

Spatial distance

property pxsizex

||pixel right - pixel left|| (x)

Type:

Spatial distance

property pxsizey

||pixel bottom - pixel top|| (y)

Type:

Spatial distance

property pxvec

(pixel bottom right - pixel top left)

Type:

Spatial vector

property pxtbvec

(pixel bottom left - pixel top left)

Type:

Spatial vector

property pxlrvec

(pixel top right - pixel top left)

Type:

Spatial vector

__eq__(other)[source]

Returns self.equals

__ne__(other)[source]

Returns not self.equals

share_area(other)[source]

Binary predicate: Does other share area with self

Parameters

other: Footprint or shapely object

Returns

bool

equals(other)[source]

Binary predicate: Is other Footprint exactly equal to self

Parameters

other: Footprint

Returns

bool

almost_equals(other)[source]

Binary predicate: Is other Footprint almost equal to self with regard to buzz.env.significant.

Parameters

other: Footprint

Returns

bool

same_grid(other)[source]

Binary predicate: Does other Footprint lie on the same grid as self

Parameters

other: Footprint

Returns

bool

property shape

(pixel per column, pixel per line)

Type:

Pixel quantities

property meshgrid_raster

Compute indice matrices

Returns

(x, y): (np.ndarray, np.ndarray)

Raster indices matrices with shape = self.shape with dtype = env.default_index_dtype

property meshgrid_spatial

Compute coordinate matrices

Returns

(x, y): (np.ndarray, np.ndarray)

Spatial coordinate matrices with shape = self.shape with dtype = float32

meshgrid_raster_in(other, dtype=None, op=<ufunc 'floor'>)[source]

Compute raster coordinate matrices of self in other referential

Parameters

other: Footprint
dtype: None or convertible to np.dtype

Output dtype If None: Use buzz.env.default_index_dtype

op: None or function operating on a vector

Function to apply before casting output to dtype If None: Do not transform data before casting

Returns

(x, y): (np.ndarray, np.ndarray)

Raster coordinate matrices with shape = self.shape with dtype = dtype

slice_in(other, clip=False)[source]

Compute location of self inside other with slice objects. If other and self do not have the same rotation, operation is undefined

Parameters

other: Footprint
clip: bool
False

Does nothing

True

Clip the slices to other bounds. If other and self do not share area, at least one of the returned slice will have slice.start == slice.stop

Returns

(yslice, xslice): (slice, slice)

Example

Burn small into big if small is within big >>> big_data[small.slice_in(big)] = small_data

Burn small into big where overlapping >>> big_data[small.slice_in(big, clip=True)] = small_data[big.slice_in(small, clip=True)]

spatial_to_raster(xy, dtype=None, op=<ufunc 'floor'>)[source]

Convert xy spatial coordinates to raster xy indices

Parameters

xy: sequence of numbers of shape (…, 2)

Spatial coordinates

dtype: None or convertible to np.dtype

Output dtype If None: Use buzz.env.default_index_dtype

op: None or vectorized function

Function to apply before casting output to dtype If None: Do not transform data before casting

Returns

out_xy: np.ndarray

Raster indices with shape = np.asarray(xy).shape with dtype = dtype

Prototype inspired from https://mapbox.github.io/rasterio/api/rasterio.io.html#rasterio.io.TransformMethodsMixin.index

raster_to_spatial(xy)[source]

Convert xy raster coordinates to spatial coordinates

Parameters

xy: sequence of numbers of shape (…, 2)

Raster coordinages

Returns

out_xy: np.ndarray

Spatial coordinates with shape = np.asarray(xy).shape with dtype = dtype

find_lines(arr, output_offset='middle', merge=True)[source]

Create a list of line-strings from a mask. Works with connectivity 4 and 8. The input raster is preprocessed using skimage.morphology.thin. The output linestrings are postprocessed using shapely.ops.linemerge.

Warning

All standalone pixels contained in arr will be ignored.

Parameters

arr: np.ndarray of bool of shape (self.shape)
output_offset: ‘middle’ or (nbr, nbr)

Coordinate offset in meter if middle: substituted by self.pxvec / 2

Returns

list of shapely.geometry.LineString

Exemple

>>> import buzzard as buzz
>>> import numpy as np
>>> import networkx as nx
>>> with buzz.Env(allow_complex_footprint=1):
...     a = np.asarray([
...         [0, 1, 1, 1, 0],
...         [0, 1, 0, 0, 0],
...         [0, 1, 1, 1, 0],
...         [0, 1, 0, 0, 0],
...         [0, 1, 1, 0, 0],
...
...     ])
...     fp = buzz.Footprint(gt=(0, 1, 0, 0, 0, 1), rsize=(a.shape))
...     lines = fp.find_lines(a, (0, 0))
...
...     # Display input / output
...     print(fp)
...     print(a.astype(int))
...     for i, l in enumerate(lines, 1):
...         print(f'edge-id:{i} of type:{type(l)} and length:{l.length}')
...         print(fp.burn_lines(l).astype(int) * i)
...
...     # Build a networkx graph
...     g = nx.Graph([(l.coords[0], l.coords[-1]) for l in lines])
...     print(repr(g.degree))
...
Footprint(tl=(0.000000, 0.000000), scale=(1.000000, 1.000000), angle=0.000000, rsize=(5, 5))
[[0 1 1 1 0]
 [0 1 0 0 0]
 [0 1 1 1 0]
 [0 1 0 0 0]
 [0 1 1 0 0]]
edge-id:1 of type:<class 'shapely.geometry.linestring.LineString'> and length:2.0
[[0 0 0 0 0]
 [0 0 0 0 0]
 [0 1 1 1 0]
 [0 0 0 0 0]
 [0 0 0 0 0]]
edge-id:2 of type:<class 'shapely.geometry.linestring.LineString'> and length:3.0
[[0 0 0 0 0]
 [0 0 0 0 0]
 [0 2 0 0 0]
 [0 2 0 0 0]
 [0 2 2 0 0]]
edge-id:3 of type:<class 'shapely.geometry.linestring.LineString'> and length:4.0
[[0 3 3 3 0]
 [0 3 0 0 0]
 [0 3 0 0 0]
 [0 0 0 0 0]
 [0 0 0 0 0]]
DegreeView({(3.0, 2.0): 1, (1.0, 2.0): 3, (2.0, 4.0): 1, (3.0, 0.0): 1})
burn_lines(obj, all_touched=False, labelize=False)[source]

Creates a 2d image from lines. Uses gdal.Polygonize.

Parameters

obj: shapely line or nested iterators over shapely lines
labelize: bool
  • if False: Create a boolean mask

  • if True: Create an integer matrix containing lines indices from order in input

Returns

np.ndarray
  • of bool or uint8 or int

  • of shape (self.shape)

find_polygons(mask)[source]

Creates a list of polygons from a mask. Uses gdal.Polygonize.

Warning

This method is not equivalent to cv2.findContours that considers that pixels are points and therefore returns the indices of the pixels of the contours of the features.

This method consider that the pixels are areas and therefore returns the coordinates of the points that surrounds the features.

Warning

Some inputs that may produce invalid polygons (see below) are fixed with the shapely.geometry.Polygon.buffer method.

Shapely will issue several warnings while buzzard fixes the polygons.

>>> # 0 0 0 0 0 0 0
... # 0 1 1 1 0 0 0
... # 0 1 1 1 1 0 0
... # 0 1 1 1 0 1 0  <- This feature has a hole near an edge. GDAL produces a self
... # 0 1 1 1 1 1 1     touching polygon without holes. A polygon with one hole is
... # 0 1 1 1 1 1 1     returned with this method.
... # 0 0 0 0 0 0 0

Parameters

mask: np.ndarray of bool of shape (self.shape)

Returns

list of shapely.geometry.Polygon

burn_polygons(obj, all_touched=False, labelize=False)[source]

Creates a 2d image from polygons. Uses gdal.RasterizeLayer.

Warning

This method is not equivalent to cv2.drawContours that considers that pixels are points and therefore expect as input the indices of the outer pixels of each feature.

This method consider that the pixels are areas and therefore expect as input the coordinates of the points surrounding the features.

Parameters

obj: shapely polygon or nested iterators over shapely polygons
all_touched: bool

Burn all polygons touched

Returns

np.ndarray

of bool or uint8 or int of shape (self.shape)

Examples

>>> burn_polygons(poly)
>>> burn_polygons([poly, poly])
>>> burn_polygons([poly, poly, [poly, poly], multipoly, poly])
tile(size, overlapx=0, overlapy=0, boundary_effect='extend', boundary_effect_locus='br')[source]

Tile a Footprint to a matrix of Footprint

Parameters

size: (int, int)

Tile width and tile height, in pixel

overlapx: int

Width of a tile overlapping with each direct horizontal neighbors, in pixel

overlapy: int

Height of a tile overlapping with each direct vertical neighbors, in pixel

boundary_effect: {‘extend’, ‘exclude’, ‘overlap’, ‘shrink’, ‘exception’}

Behevior at boundary effect locus

  • ‘extend’
    • Preserve tile size

    • Preserve overlapx and overlapy

    • Sacrifice global bounds, results in tiles partially outside bounds at locus (if necessary)

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘overlap’
    • Preserve tile size

    • Sacrifice overlapx and overlapy, results in tiles overlapping more at locus (if necessary)

    • Preserve global bounds

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘exclude’
    • Preserve tile size

    • Preserve overlapx and overlapy

    • Preserve global bounds

    • Sacrifice tile count, results in tiles excluded at locus (if necessary)

    • Sacrifice boundary pixels coverage at locus (if necessary)

  • ‘shrink’
    • Sacrifice tile size, results in tiles shrinked at locus (if necessary)

    • Preserve overlapx and overlapy

    • Preserve global bounds

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘exception’
    • Raise an exception if tiles at locus do not lie inside the global bounds

boundary_effect_locus: {‘br’, ‘tr’, ‘tl’, ‘bl’}

Locus of the boundary effects

  • ‘br’ : Boundary effect occurs at the bottom right corner of the raster, top left coordinates are preserved

  • ‘tr’ : Boundary effect occurs at the top right corner of the raster, bottom left coordinates are preserved

  • ‘tl’ : Boundary effect occurs at the top left corner of the raster, bottom right coordinates are preserved

  • ‘bl’ : Boundary effect occurs at the bottom left corner of the raster, top right coordinates are preserved

Returns

np.ndarray
  • of dtype=object (Footprint)

  • of shape (M, N)

    • with M the line count

    • with N the column count

tile_count(rowcount, colcount, overlapx=0, overlapy=0, boundary_effect='extend', boundary_effect_locus='br')[source]

Tile a Footprint to a matrix of Footprint

Parameters

rowcount: int

Tile count per row

colcount: int

Tile count per column

overlapx: int

Width of a tile overlapping with each direct horizontal neighbors, in pixel

overlapy: int

Height of a tile overlapping with each direct vertical neighbors, in pixel

boundary_effect: {‘extend’, ‘exclude’, ‘overlap’, ‘shrink’, ‘exception’}

Behevior at boundary effect locus

  • ‘extend’
    • Preserve tile size

    • Preserve overlapx and overlapy

    • Sacrifice global bounds, results in tiles partially outside bounds at locus (if necessary)

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘overlap’
    • Preserve tile size

    • Sacrifice overlapx and overlapy, results in tiles overlapping more at locus (if necessary)

    • Preserve global bounds

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘exclude’
    • Preserve tile size

    • Preserve overlapx and overlapy

    • Preserve global bounds

    • Preserve tile count

    • Sacrifice boundary pixels coverage at locus (if necessary)

  • ‘shrink’
    • Sacrifice tile size, results in tiles shrinked at locus (if necessary)

    • Preserve overlapx and overlapy

    • Preserve global bounds

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘exception’
    • Raise an exception if tiles at locus do not lie inside the global bounds

boundary_effect_locus: {‘br’, ‘tr’, ‘tl’, ‘bl’}

Locus of the boundary effects

  • ‘br’ : Boundary effect occurs at the bottom right corner of the raster, top left coordinates are preserved

  • ‘tr’ : Boundary effect occurs at the top right corner of the raster, bottom left coordinates are preserved

tile_occurrence(size, pixel_occurrencex, pixel_occurrencey, boundary_effect='extend', boundary_effect_locus='br')[source]

Tile a Footprint to a matrix of Footprint Each pixel occur pixel_occurrencex * pixel_occurrencey times overall in the output

Parameters

size: (int, int)

Tile width and tile height, in pixel

pixel_occurrencex: int

Number of occurence of each pixel in a line of tile

pixel_occurrencey: int

Number of occurence of each pixel in a column of tile

boundary_effect: {‘extend’, ‘exclude’, ‘overlap’, ‘shrink’, ‘exception’}

Behavior at boundary effect locus

  • ‘extend’
    • Preserve tile size

    • Preserve overlapx and overlapy

    • Sacrifice global bounds, results in tiles partially outside bounds at locus (if necessary)

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘overlap’
    • Preserve tile size

    • Sacrifice overlapx and overlapy results in tiles overlapping more at locus (if necessary)

    • Preserve global bounds

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘exclude’
    • Preserve tile size

    • Preserve overlapx and overlapy

    • Preserve global bounds

    • Sacrifice tile count, results in tiles excluded at locus (if necessary)

    • Sacrifice boundary pixels coverage at locus (if necessary)

  • ‘shrink’
    • Sacrifice tile size, results in tiles shrinked at locus (if necessary)

    • Preserve overlapx and overlapy

    • Preserve global bounds

    • Preserve tile count

    • Preserve boundary pixels coverage

  • ‘exception’

    Raise an exception if tiles at locus do not lie inside the global bounds

boundary_effect_locus: {‘br’, ‘tr’, ‘tl’, ‘bl’}

Locus of the boundary effects

  • ‘br’ : Boundary effect occurs at the bottom right corner of the raster top left coordinates are preserved

  • ‘tr’ : Boundary effect occurs at the top right corner of the raster, bottom left coordinates are preserved

  • ‘tl’ : Boundary effect occurs at the top left corner of the raster, bottom right coordinates are preserved

  • ‘bl’ : Boundary effect occurs at the bottom left corner of the raster, top right coordinates are preserved

Returns

np.ndarray
  • of dtype=object (Footprint)

  • of shape (M, N)
    • with M the line count

    • with N the column count

__str__()[source]

Return str(self).

__repr__()[source]

Return repr(self).

__reduce__()[source]

Helper for pickle.

__hash__()[source]

Return hash(self).

forward_conv2d(kernel_size, stride=1, padding=0, dilation=1)[source]

Shift, scale and dilate the Footprint as if it went throught a 2d convolution kernel.

The arithmetic followed is the one from pytorch, but other deep-learning libraries mostly follow the same arithmetic.

This function is a many to one mapping, two footprints with different rsizes can produce the same Footprint when stride > 1.

Parameters

kernel_size: int or (int, int)

See torch.nn.Conv2d documentation.

stride: int or (int, int)

See torch.nn.Conv2d documentation.

padding: int or (int, int)

See torch.nn.Conv2d documentation.

dilation: int or (int, int)

See torch.nn.Conv2d documentation.

Returns

Footprint

Example

>>> fp0 = buzz.Footprint(tl=(0, 0), size=(1024, 1024), rsize=(1024, 1024))
... fp1 = fp0.forward_conv2d(kernel_size=2, stride=2)
... print(fp1)
Footprint(tl=(0.5, -0.5), size=(1024, 1024), rsize=(512, 512))
backward_conv2d(kernel_size, stride=1, padding=0, dilation=1)[source]

Shift, scale and dilate the Footprint as if it went backward throught a 2d convolution kernel.

The arithmetic followed is the one from pytorch, but other deep-learning libraries mostly follow the same arithmetic.

This function is a one to one mapping, two different input footprints will produce two different output Footprints. It means that the backward_conv2d of a forward_conv2d may not reproduce the initial Footprint, some pixels on the bottom and right edges may be missing.

Parameters

kernel_size: int or (int, int)

See torch.nn.Conv2d documentation.

stride: int or (int, int)

See torch.nn.Conv2d documentation.

padding: int or (int, int)

See torch.nn.Conv2d documentation.

dilation: int or (int, int)

See torch.nn.Conv2d documentation.

Returns

Footprint

Example

>>> fp1 = buzz.Footprint(tl=(0.5, -0.5), size=(1024, 1024), rsize=(512, 512))
... fp0 = fp1.backward_conv2d(kernel_size=2, stride=2)
... print(fp0)
Footprint(tl=(0, 0), size=(1024, 1024), rsize=(1024, 1024))
forward_convtranspose2d(kernel_size, stride=1, padding=0, dilation=1, output_padding=0)[source]

Shift, scale and dilate the Footprint as if it went throught a 2d transposed convolution kernel.

The arithmetic followed is the one from pytorch, but other deep-learning libraries mostly follow the same arithmetic.

A 2d transposed convolution has 4 internal steps: 1. Apply stride (i.e. interleave the input pixels with zeroes) 2. Add padding 3. Apply a 2d convolution with stride=1 and pad=0 4. Add output-padding

This function is a one to one mapping, two different input footprints will produce two different output Footprints.

Parameters

kernel_size: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

stride: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

padding: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

dilation: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

output_padding: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

Returns

Footprint

Example

>>> fp0 = buzz.Footprint(tl=(0, 0), size=(1024, 1024), rsize=(512, 512))
... fp1 = fp0.forward_convtranspose2d(kernel_size=3, stride=2, padding=1)
... print(fp1)
Footprint(tl=(0, 0), size=(1023, 1023), rsize=(1023, 1023))
backward_convtranspose2d(kernel_size, stride=1, padding=0, dilation=1, output_padding=0)[source]

Shift, scale and dilate the Footprint as if it went backward throught a 2d transposed convolution kernel.

The arithmetic followed is the one from pytorch, but other deep-learning libraries mostly follow the same arithmetic.

A 2d transposed convolution has 4 internal steps: 1. Apply stride (interleave the input pixels with zeroes) 2. Add padding 3. Apply a 2d convolution stride:1, pad:0 4. Add output-padding

This function is a one to one mapping, two different input Footprints will produce two different output Footprints.

Parameters

kernel_size: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

stride: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

padding: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

dilation: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

output_padding: int or (int, int)

See torch.nn.ConvTranspose2d documentation.

Returns

Footprint

Example

>>> fp0 = buzz.Footprint(tl=(0, 0), size=(1023, 1023), rsize=(1023, 1023))
... fp1 = fp0.backward_convtranspose2d(kernel_size=3, stride=2, padding=1)
... print(fp1)
Footprint(tl=(0, 0), size=(1024, 1024), rsize=(512, 512))