imagen.sheetcoords

Submodules

• imagen.sheetcoords.pyc

Module

Provides SheetCoordinateSystem, allowing conversion between the two coordinate systems used in ImaGen.

‘Sheet coordinates’ allow simulation parameters to be specified in units that are density-independent, whereas ‘matrix coordinates’ provide a means of realizing the continuous sheets.

Hence we can have a pair of ‘sheet coordinates’ (x,y); floating-point Cartesian coordinates indicating an arbitrary point on the sheet’s plane. We can also have a pair of ‘matrix coordinates’ (r,c), which are used to address an underlying matrix. These matrix coordinates are also floating-point numbers to allow precise conversion between the two schemes. Where it is necessary to address a specific element of the matrix (as is often the case in calculations), we also have the usual matrix index coordinates (r_idx, c_idx). We refer to these as matrixidx coordinates. SheetCoordinateSystem provies methods for converting between sheet and matrix coordinates, as well as sheet and matrixidx coordinates.

Everyone should use these facilities for conversions between the two coordinate systems to guarantee consistency.

Example of how the matrix stores the representation of the Sheet

For the purposes of this example, assume the goal is a Sheet with density=3 that has a 1 at (-1/2,-1/2), a 5 at (0.0,0.0), and a 9 at (1/2,1/2). More precisely, for this Sheet,

the continuous area from -1/2,-1/2 to -1/6,-1/6 has value 1, the continuous area from -1/6,-1/6 to 1/6,1/6 has value 5, and the continuous area from 1/6,1/6 to 1/2,1/2 has value 9.

With the rest of the elements filled in, the Sheet would look like:

 (-1/2,1/2) -+-----+-----+-----+- (1/2,1/2)
             |     |     |     |
             |  7  |  8  |  9  |
             |     |     |     |
 (-1/2,1/6) -+-----+-----+-----+- (1/2,1/6)
             |     |     |     |
             |  4  |  5  |  6  |
             |     |     |     |
(-1/2,-1/6) -+-----+-----+-----+- (1/2,-1/6)
             |     |     |     |
             |  1  |  2  |  3  |
             |     |     |     |
(-1/2,-1/2) -+-----+-----+-----+- (1/2,-1/2)

where element 5 is centered on 0.0,0.0. A matrix that would match these Sheet coordinates is:

[[7 8 9]
 [4 5 6]
 [1 2 3]]

If we have such a matrix, we can access it in one of two ways: Sheet or matrix/matrixidx coordinates. In matrixidx coordinates, the matrix is indexed by rows and columns, and it is possible to ask for the element at location [0,2] (which returns 9 as in any normal row-major matrix). But the values can additionally be accessed in Sheet coordinates, where the matrix is indexed by a point in the Cartesian plane. In Sheet coordinates, it is possible to ask for the element at location (0.3,0.02), which returns floating-point matrix coordinates that can be cropped to give the nearest matrix element, namely the one with value 6.

Of course, it would be an error to try to pass matrix coordinates like [0,2] to the sheet2matrix calls; the result would be a value far outside of the actual matrix.

class imagen.sheetcoords.SheetCoordinateSystem(bounds, xdensity, ydensity=None)

Bases: object

Provides methods to allow conversion between sheet and matrix coordinates.

closest_cell_center(x, y)

Given arbitary sheet coordinates, return the sheet coordinates of the center of the closest unit.

matrix2sheet(float_row, float_col)

Convert a floating-point location (float_row,float_col) in matrix coordinates to its corresponding location (x,y) in sheet coordinates.

Valid for scalar or array float_row and float_col.

Inverse of sheet2matrix().

matrixidx2sheet(row, col)

Return (x,y) where x and y are the floating point coordinates of the center of the given matrix cell (row,col). If the matrix cell represents a 0.2 by 0.2 region, then the center location returned would be 0.1,0.1.

NOTE: This is NOT the strict mathematical inverse of sheet2matrixidx(), because sheet2matrixidx() discards all but the integer portion of the continuous matrix coordinate.

Valid only for scalar or array row and col.

sheet2matrix(x, y)

Convert a point (x,y) in Sheet coordinates to continuous matrix coordinates.

Returns (float_row,float_col), where float_row corresponds to y, and float_col to x.

Valid for scalar or array x and y.

Note about Bounds For a Sheet with BoundingBox(points=((-0.5,-0.5),(0.5,0.5))) and density=3, x=-0.5 corresponds to float_col=0.0 and x=0.5 corresponds to float_col=3.0. float_col=3.0 is not inside the matrix representing this Sheet, which has the three columns (0,1,2). That is, x=-0.5 is inside the BoundingBox but x=0.5 is outside. Similarly, y=0.5 is inside (at row 0) but y=-0.5 is outside (at row 3) (it’s the other way round for y because the matrix row index increases as y decreases).

sheet2matrixidx(x, y)

Convert a point (x,y) in sheet coordinates to the integer row and column index of the matrix cell in which that point falls, given a bounds and density. Returns (row,column).

Note that if coordinates along the right or bottom boundary are passed into this function, the returned matrix coordinate of the boundary will be just outside the matrix, because the right and bottom boundaries are exclusive.

Valid for scalar or array x and y.

sheetcoordinates_of_matrixidx()

Return x,y where x is a vector of sheet coordinates representing the x-center of each matrix cell, and y represents the corresponding y-center of the cell.

xdensity

The spacing between elements in an underlying matrix representation, in the x direction.

ydensity

The spacing between elements in an underlying matrix representation, in the y direction.

class imagen.sheetcoords.Slice

Bases: numpy.ndarray

Represents a slice of a SheetCoordinateSystem; i.e., an array specifying the row and column start and end points for a submatrix of the SheetCoordinateSystem.

The slice is created from the supplied bounds by calculating the slice that corresponds most closely to the specified bounds. Therefore, the slice does not necessarily correspond exactly to the specified bounds. The bounds that do exactly correspond to the slice are available via the ‘bounds’ attribute.

Note that the slice does not respect the bounds of the SheetCoordinateSystem, and that actions such as translate() also do not respect the bounds. To ensure that the slice is within the SheetCoordinateSystem’s bounds, use crop_to_sheet().

crop_to_sheet(sheet_coord_system)

Crop the slice to the SheetCoordinateSystem’s bounds.

positionedcrop(x, y, sheet_coord_system)

Offset the bounds_template to this cf’s location and store the result in the ‘bounds’ attribute.

Also stores the input_sheet_slice for access by C.

positionlesscrop(x, y, sheet_coord_system)

Return the correct slice for a weights/mask matrix at this ConnectionField’s location on the sheet (i.e. for getting the correct submatrix of the weights or mask in case the unit is near the edge of the sheet).

set(slice_specification)

Set this slice from some iterable that specifies (r1,r2,c1,c2).

shape_on_sheet()

Return the shape of the array that this Slice would give on its sheet.

submatrix(matrix)

Return the submatrix of the given matrix specified by this slice.

Equivalent to computing the intersection between the SheetCoordinateSystem’s bounds and the bounds, and returning the corresponding submatrix of the given matrix.

The submatrix is just a view into the sheet_matrix; it is not an independent copy.

translate(r, c)

Translate the slice by the specified number of rows and columns.