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
/local/homes/rhaschke/nst7/man/../o.linx86//../foldersrc/nst_util.c