pixelscan
The pixelscan library provides functions to scan pixels on a grid in a variety of spatial patterns. The library consists of scan generators and coordinate transformations. Scan generators are Python generators that return pixel coordinates in a particular spatial pattern. Coordinate transformations are iterators that apply spatial transformations to the coordinates created by the scan generators. Transformation can be chained to yield very generic transformations.
Documentation
See the library API documentation here.
Usage
The typical calling syntax is
for x, y in transformation(generator(...), ...):
foo(x,y)For example, the following scans pixels in a clockwise circular pattern from the origin up to a radius of one
for x, y in snap(circlescan(0, 0, 0, 1)):
print(x, y)and will generate the following points
(0,0), (0,1), (1,1), (1,0), (1,-1), (0,-1), (-1,-1), (-1,0), (-1,1)To skip every other pixel a skip transformation can be applied
for x, y in snap(skip(circlescan(0, 0, 0, 1), step=2)):
print(x, y)which will generate the following points
(0,0), (1,1), (1,-1), (-1,-1), (-1,1)Scan Generators
The following are the currently available generators
| Name | Description |
|---|---|
| circlescan | Generates pixels in a clockwise circular pattern |
|
x0, y0, r1, r2 = 0, 0, 0, 2
for x, y in snap(circlescan(x0, y0, r1, r2)):
print(x, y)where x0 = Circle x center
y0 = Circle y center
r1 = Initial radius
r2 = Final radiusproduces the following points: ( 0, 0) ( 0, 1) ( 1, 1) ( 1, 0) ( 1,-1) ( 0,-1)
(-1,-1) (-1, 0) (-1, 1) ( 0, 2) ( 1, 2) ( 2, 1)
( 2, 0) ( 2,-1) ( 1,-2) ( 0,-2) (-1,-2) (-2,-1)
(-2, 0) (-2, 1) (-1, 2) |
| gridscan | Generates pixels in rectangular grid pattern |
|
xi, yi, xf, yf = 0, 0, 2, 2
for x, y in gridscan(xi, yi, xf, yf, stepx=1, stepy=1):
print(x, y)where xi = Initial x-coordinate
yi = Initial y-coordinate
xf = Final x-coordinate
yf = Final y-coordinate
stepx = Step size in x-coordinate
stepy = Step size in y-coordinateproduces the following points: (0,0) (1,0) (2,0) (0,1) (1,1) (2,1) (0,2) (1,2) (2,2) |
| hilbertscan | Generates pixels in a Hilbert curve pattern |
|
size, distance = 4, 16
for x, y in hilbertscan(size, distance):
print(x, y)where size = Size of enclosing square
distance = Distance along curveproduces the following points: (0,0), (0,1), (1,1), (1,0), (2,0), (3,0), (3,1), (2,1)
(2,2), (3,2), (3,3), (2,3), (1,3), (1,2), (0,2), (0,3) |
| ringscan - chebyshev | Generates pixels in a ring pattern (squares) |
|
x0, y0, r1, r2 = 0, 0, 0, 2
for x, y in ringscan(x0, y0, r1, r2, metric=chebyshev):
print(x, y)where x0 = Circle x center
y0 = Circle y center
r1 = Initial radius
r2 = Final radius
r2 = Final radius
metric = Distance metricproduces the following points: ( 0, 0) ( 0, 1) ( 1, 1) ( 1, 0) ( 1,-1) ( 0,-1)
(-1,-1) (-1, 0) (-1, 1) ( 0, 2) ( 1, 2) ( 2, 2)
( 2, 1) ( 2, 0) ( 2,-1) ( 2,-2) ( 1,-2) ( 0,-2)
(-1,-2) (-2,-2) (-2,-1) (-2, 0) (-2, 1) (-2,2) (-1,2) |
| ringscan - manhattan | Generates pixels in a ring pattern (diamonds) |
|
x0, y0, r1, r2 = 0, 0, 0, 2
for x, y in ringscan(x0, y0, r1, r2, metric=manhattan):
print(x, y)where x0 = Circle x center
y0 = Circle y center
r1 = Initial radius
r2 = Final radius
metric = Distance metricproduces the following points: ( 0, 0) ( 0, 1) ( 1, 0) ( 0,-1) (-1, 0) ( 0, 2)
( 1, 1) ( 2, 0) ( 1,-1) ( 0,-2) (-1,-1) (-2, 0) (-1, 1) |
| snakescan | Generates pixels in a snake pattern along the x then y axis |
|
xi, yi, xf, yf = 0, 0, 2, 2
for x, y in snakescan(xi, yi, xf, yf):
print(x, y)where xi = Initial x-coordinate
yi = Initial y-coordinate
xf = Final x-coordinate
yf = Final y-coordinateproduces the following points: ( 0, 0) ( 1, 0) ( 2, 0) ( 2, 1) ( 1, 1) ( 0, 1)
( 0, 2) ( 1, 2) ( 2, 2) |
| walkscan | Generates pixels in a random pattern using a random walk |
|
random.seed(0)
x0, y0, = 0, 0
for x, y in skip(walkscan(x0, y0, xn=0.25, xp=0.25,
yn=0.25, yp=0.25), stop=8):
print(x, y)where x0 = Initial x-coordinate
y0 = Initial y-coordinate
xn = Probability of moving in the negative x direction
xp = Probability of moving in the positive x direction
yn = Probability of moving in the negative y direction
yp = Probability of moving in the positive y directionproduces the following points: ( 0, 0) ( 0, 1) ( 0, 2) ( 1, 2) ( 2, 2) ( 2, 1)
( 3, 1) ( 3, 2) ( 4, 2) |
Coordinate Transformations
The following are the currently available transformations
| Name | Description |
|---|---|
| clip | Clips the coordinates at the given boundary |
Syntax: clip(scan,
minx = int,
maxx = int,
miny = int,
maxy = int,
predicate = function,
abort = bool)where scan = Pixel scan generator
minx = Minimum x-coordinate (default = -sys.maxint)
maxx = Maximum x-coordinate (default = sys.maxint)
miny = Minimum y-coordinate (default = -sys.maxint)
maxy = Maximum y-coordinate (default = sys.maxint)
predicate = Optional function that takes 2 arguments (x and y)
and returns true if coordinate should be kept
otherwise false (default = None)
abort = Abort iteration if boundary is crossed |
|
| reflection | Reflects the coordinates along the x and/or y axis |
Syntax: reflection(scan, rx = bool, ry = bool)where scan = Pixel scan generator
rx = True if x-coordinate should be reflected (default=False)
ry = True if y-coordinate should be reflected (default=False) |
|
| reservoir | Randomly samples the pixels using reservoir sampling |
Syntax: reservoir(scan, npoints = int)where scan = Pixel scan generator
npoints = Sample size |
|
| rotation | Rotates the coordinates about the origin counter-clockwise |
Syntax: rotation(scan, angle = float)where scan = Pixel scan generator
angle = Counter-clockwise angle in degrees (default=0) |
|
| sample | Randomly samples the pixels with a given probability |
Syntax: sample(scan, probability = float)where scan = Pixel scan generator
probability = Sampling probability in interval [0,1] (default=1) |
|
| scale | Scales the coordinates with a given scale factors |
Syntax: scale(scan, sx = float, sy = float)where scan = Pixel scan generator
sx = x-coordinate scale factor (default=1)
sy = y-coordinate scale factor (default=1) |
|
| skip | Skips the pixels with the given step size |
Syntax: skip(scan, start = int, stop = int, step = int)where scan = Pixel scan generator
start = Iteration starting 0-based index (default = 0)
stop = Iteration stopping 0-based index (default = sys.maxint)
step = Iteration step size (default = 1) |
|
| snap | Snap the x and y coordinates to the nearest grid point |
Syntax: snap(scan)where scan = Pixel scan generator |
|
| swap | Swap the x and y coordinates |
Syntax: swap(scan)where scan = Pixel scan generator |
|
| translation | Translates the coordinates by the given offsets |
Syntax: translation(scan, tx = float, ty = float)where scan = Pixel scan generator
tx = x-coordinate translation offset (default = 0)
ty = y-coordinate translation offset (default = 0) |
|
Warnings
Scan Generators such as circlescan and Coordinate Transformations such as rotation can yield non-grid points. They can be snapped to a grid point using the snap transformation.