NAME
spatial_operator -- scan image with operation of other unit
PROTOTYPE
unitptr spatial_operator( int iNumIm, int iDx, int iDy, int iDx1, int iDy1, int iDim, int iNumPos, int *piPos, char *tOptStr, 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 iDim
- output dim of iterated unit
- int iNumPos
- nr of subrectangle positions
- int *piPos
- array of iNumPos positions
- char *tOptStr
- option string
- unitptr uHost
- host unit
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
INTERFACE:
The action of the spatial_operator
unit is very similar to that of the .iterator unit, but specialized
to iterating a unit over a two-dimensional pixel area instead of
a one-dimensional index range.
The created unit will have the following fields (read the description
first):
- X_in[iDx*iDy*iNumIm]:
- packed input field holding iNumIm image layers
for input (concatenated to a single large array)
- Y_in[iNumPos*iDim]:
- packed input field holding target values for
iNumPos pixel positions in input image rectangle.
(concatenated to a single
large array)
- Z_in[iDim]:
- input expecting at each iteration a result vector
for the current pixel position.
vector should be computed by the iterated unit,
using the data in the current pixel rectangle
offered at Y_out of the spatial_operator unit.
Thus, connect this input to a suitable output of
the iterated unit.
The spatial_operator unit assembles the result
vectors into iDim pixel rectangles, that are
(sequentially concatenated) available at X_out
after all iterations have been made.
ne Thus, this input must be connected to a suitable
output of the iterated unit.
- in_3[2*iNumPos]:
- (packed input field) Specifies iNumPos pixel
positions at which the iterated
unit shall be applied.
- CTL_in[0]:
- control input.
- X_out[iNumPos*iDim]:
- packed output field, holding assembled
result values for
iNumPos positions (concatenated to a single
large array. The first iNumPos array elements
contain the first components of the per-pixel
result vectors, the second iNumPos array elements
the second components and so on )
- Y_out[iNumIm*iDx1*iDy1]:
- output holding for each image layer a
pixel subrectangle to be processed
by iterated unit at each iteration step (concatenated
to a single large array, as for X_in ).
To be connected with corresponding
pixel input of iterated unit.
- Z_out[iDim]:
- (only used when Y_in is used): for each iterationm,
this field provides the set of iDim `target values''
for the current pixel. These values are
assigned via Y_in for the entire image.
- out_3[2]:
- This output field provides at each iteration
the (i,j) coordinates
of the current pixel (0,0) is lower left corner.
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
iteratively
at a given set S (via in_3[]) of pixel positions in an image.
For the unit u, the spatial_operator unit takes its successor
in the NST-execution queue.
If the unit u is adaptive,
it also can be trained at the same set S of positions, using at each
pixel positions a iDim dimensional target vector that is specified
(for the iNumPos pixel positions of the set) at input field
Y_in.
A single execution call of
the spatial_operator unit makes iNumPos exec_unit (and optionally,
adapt_unit calls) for its successor unit u. Each of these iNumPos
calls belongs to one of the iNumPos pixel positions of the set S
and consists of the following steps:
1. Before the the call for the i-th pixel position (x,y), the
spatial_operator unit cuts out iNumIm pixel subrectangles
(one for each of the iNumIm image `layers'') with their `hot spots''
(default is the center) centered at (x,y) in the input image X_in
and
makes them available (as a vector of the iNumIm concatenated
iDx1*iDy1 pixel blocks) at output field Y_out for use by the iterator
unit u in the impending exec_unit call.
2. Likewise, the spatial_operator unit provides at its output field
Z_out the iDim dimensional target vector that is specified at
Y_in for the i-th pixel location (this is taken to be th i-th
block of iDim elements in the iDim*iNumPos dimensional input
Y_in).
3. Finally, the spatial_operator unit provides at its output field
out_3 the (integer valued) pixel coordinates (x,y) of the current
pixel position.
4. After 1-3, the spatial_operator unit makes a single exec_unit call
for its successor unit u. u is expected to use the data provided
at output fields Y_out..out_3 of the spatial_operator unit
(i.e., current pixel subrectangle with hot spot at current pixel
location (x,y), target values for (x,y) and (x,y) - coordinates
themselves) for its local computations (this requires to set up
suitable connections between the mentioned output fields and
suitable input fields of u) and to provide its result value
at some iDim - dimensional
output field that is referred to as ResultField in
the following.
5. After the exec_unit call to the iterated unit u, control returns
to the spatial_operator unit. The spatial_operator unit now
assumes to find
iDim result values that were computed by the iterated unit
at its (the spatial_operator unit's)
input field Z_in (this requires a suitable connection
with the ResultField of the iterated unit to be present). It
copies these values into its (the spatial_operator unit's)
output field X_out at index positions
i + j*iNumPos (.j=0..iDim-1).
Steps 1.-5. are repeated for all pixel positions i=0..iNumPos-1.
After that, one exec_unit call of the spatial_operator unit
is completed.
The result are the iDim*iNumPos values at output field X_out,
holding the iDim dimensional result vectors of the iNumPos
local computations of the iterated unit in the form of iDim
concatenated pixel arrays (each consisting of iNumPos values)
that correspond to components 0,1,..iDim-1 of the iDim dimensional
result vectors.
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 spatial_operator unit. The following options are provided:
- %u
- unbuffered, i.e. omit automatic prefixing of
adapt_unit - call by exec_unit - call.
- %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.
- %iO
- specify the number of operands as i (missing or
nonpositive values of i are taken as the default 1).
This has the effect to include i (instead of 1) successor
of the spatial_operator unit in each execution/adaptation call.
- %i:jo
- set `hot spot'' (hx,hy) to (i,j). This has the effect to
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
- make hot spot `blind'': the effect will be
that the input at the hot spot will always
be tied to value zero, i.e. this projects out the effect of any
`position diagonal'' part in the mapping.
- %fa
- add `attention control''-input field. If this option is
specified, an additional packed input field of iNumPos pins
(the `attention control field) will be
created. The pixel subset S over which the operations of the
iterated unit are performed is the additionally restricted
to the subset of those
locations, for which the input values at the corresponding
attention control field pin exceeds the threshold value f.
For all other locations, the operation of the iterated
unit will be omitted and a result value of zero will be
substituted instead.
DEFAULTS:
If iNumPos=0 and pfPos=NULL, all pixel positions in
the input image are used and the value iNumPos=iDx*iDy
is substituted. 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.
SEE ALSO:
mapper, iterator
FILE
/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../foldersrc/nst_pixel.c