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))