NAME

mapper -- unit to map network across image

PROTOTYPE

unitptr mapper( int iNumIm, int iDx, int iDy, int iDx1, int iDy1, int iNumPos, int *piPos, char *tOptStr, unitptr u, unitptr uHost)

ARGUMENTS

int iNumIm
nr of input images
int iDx
width of image rectangle
int iDy
height of image rectangle
int iDx1
width of subrectangle
int iDy1
height of subrectangle
int iNumPos
nr of subrectangle positions
int *piPos
array of iNumPos positions
char *tOptStr
option string
unitptr u
unit for mapping. NOTE: when the created mapper - unit is removed, unit u will be removed as well!
unitptr uHost
host unit

INTERFACE:

The created unit will have the same fields (in both pin numbers and type input/output and packed/unpacked) that unit u has, except for the maximally three fields X_in, Y_in and X_out (the presence of X_in is required for u, the remaining two fields are optional). For these fields, the following specification holds:
X_in[iDx*iDy*iNumIm]:
packed input field holding input images (concatenated to a single large array)
Y_in[iNumPos*iDim]:
packed input field holding target values for iNumPos positions (concatenated to a single large array)
X_out[iNumPos*iDim]:
packed output field, holding result values for iNumPos positions (concatenated to a single large array)
Here, iDim denotes the dimension of the input field Y_in and of the output field X_out of unit u (which must have the same number of pins).

DESCRIPTION:

This unit is provided to apply a mapping implemented by a unit u at a set of multiple positions in an image. If the mapping is adaptive, it also can be trained at the same set of positions. The image consists of iNumIm image planes of iDx x iDy pixels each. These image planes are assumed to be concatenated to form a rectangle of width iDx and height iNumIm x iDy pixels specified at packed input field X_in. The training input data are assumed to be provided at input field Y_in. The unit u is assumed to have at least one packed input field X_in of iNumIm x iDx1 x iDy1 pins, and an input field Y_in and an output field X_out of iDim pins each (the latter two may be either packed or unpacked). It may have any number of additional fields. A single execution of the mapper-unit will have the effect to execute u iNumPos times. For each effected execution of u, the input values at the input fields of unit u are taken from the inputs at the matching input fields of the mapper unit. At the i-th effected execution of u (.i=0..iNumPos-1 ), the values for X_in of u are taken from an image subrectangle of size iDx1 x iDy1 with its lower left corner offset by the vector (piPos[2*i],piPos[2*i+1]) in each of the iNumIm input images (at packed field X_in of the mapper unit). Likewise, the values for Y_in of u are taken from the iDim pins i+j*iNumPos, j=0..iDim-1, of Y_in of the mapper unit. The iDim corresponding result values are written to the iDim pins i+j*iNumPos, j=0..iDim-1, of X_out of the mapper unit. The same is valid for an adaptation call, i.e. the adapt-call for u is repeated iNumPos times, for the same sequence of the iNumPos subrectangle positions (here, the default is to precede the i-th adapt-call by an exec-call for the same image position, since the single unit u cannot buffer the iNumPos intermediate results from the previous exec-calls. If it is known, that u is of a type for which no internal results must be buffered for the adapt_unit call, these exec-calls are superfluous and can be switched of by specifying the option %u in the option string.

OPTIONS:

The option string tOptStr allows to customize the behaviour of the mapper unit. The following options are provided:
%u
unbuffered, i.e. omit automatic prefixing of adapt_unit - call by exec_unit - call.
%i:j:kF
instead of the special correspondence of fields X_in, Y_in and X_out of the mapper unit and unit u, define this correspondence for the fields in_[i], in_[j] and out_[k] of the mapper unit and unit u. To avoid that any existing input field of u is mapped as target input, specify j=-1. To avoid that any existing output field of u is interpreted as mapped output, specify k=-1.
%ix
set boundary condition along x-axis (horizontal). i=0 is output 0 for boundary positions, i=1 is periodic boundary.
%iy
set boundary condition along y-axis (vertical). i=0 is output 0 for boundary positions, i=1 is periodic boundary.
%r
instead of sequentially visiting all iNumPos specified image locations for an adapt_unit - call, choose a sequence of iNumPos independent random choices for the set of iNumPos specified locations. The resulting random sequence may, therefore, leave out some positions and contain others multiple times.
%i:jo
align pixel (i,j) of iDx1xiDy1 -input subrectangle with the specified image locations piPos[]. Default is (i,j)=(iDx1/2,iDy1/2), i.e., for iDx1, iDy1 both odd, the central pixel of the input subrectangle will be aligned with the specified positions.
%b
set `blind spot'' at pixel (i,j) specified with the previous option. The effect will be that the input at pixel (i,j) will be tied to value zero, i.e. this projects out the effect of any `position diagonal'' part in the mapping.

DEFAULTS:

If iNumPos=0 and pfPos=NULL, all pixel positions in the input image are used and the value iNumPos=iDx*iDy is assumed. The sequence of positions is arranged such that the horizontal pixel coordinate is the fast index, with the lower left corner position (0,0) coming first. If iNumPos=0 and piPos!=NULL, the positions of the grid (x,y) = (x0+i*dx0,y0+j*dy0) with (x0,y0)=(piPos[0],piPos[1]) and (dx0,dy0)=(piPos[2],piPos[3]) are used. In this case, iNumPos=(1+iDx/dx0)*(1+iDy/dy0) is assumed. The seqence of positions is arranged such that i is the fast index. iNumPos>0 and pfPos=NULL is regarded as an error.

FILE

/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../foldersrc/nst_util.c