area

Command: area


Description

Given a -- hypothetical -- twodimensional array
"area" tells you what indices you need to
subscript a contiguous twodimensional subarea.

The subarea is defined by specifying it's size
(width and height) as well as its location in the
source array. The location is defined by specifying
an anchor point in the source array as well as in
the subarea. Anchor points are matched see
illustration and examples below:

source array: height=6 width=15 anchor=(2 5)
subarea : height=4 width= 5 anchor=(1 3)
...............
..ooooo........
..oooxo........
..ooooo........
..ooooo........
...............


"area" returns an array of ONEDIMENSIONAL indices.
There is a SLI function called "area2" returning
twodimensional indices as well as the conversion
functions "cv1d" and "cv2d".
(For information on the order of subscription in NEST
arrays see references below.)

Parameters

In: "area" takes seven integer arguments (one integer
and three pairs). These arguments describe (1) the width of the
(hypothetical) source array (2) the height and width of the
subarea as well as (3&4) an anchor point in each of the two
arrays (see illustration above):

source_width : width of the (hypothetical) source
array to be subscribed into
source_anchor_y
source_anchor_x: position of the anchor point relative
to ORIGIN OF THE SOURCE ARRAY

area_heigh t : height of the subarea to be subscribed
area_width : width of the subarea to be subscribed
area_anchor_y
area_anchor_x : position of the anchor point relative
to ORIGIN OF THE SUBAREA

Out: "area" returns an array of ONEDIMENSIONAL indices:

[1d-indices] : flat integer array containing the indices
that can be used to subscript the
(hypothetical) source array in order to
access the desired subarea.

Indices are onedimensional and are returned
in standard NEST (monotonic) counting order.
(For information on the order of
subscription in NEST arrays see references
below.)

Author
Ruediger Kupper

Synopsis

source_width source_anchor_y source_anchor_x
area_height area_width area_anchor_y area_anchor_x
area -> [1d-indices]

References
(TO BE DONE: NEST layer indexing conventions)

Examples

(Examples are illustrated):

Ex. 1: source array: (height=5) width=10 anchor=(0 0)
subarea : height=3 width= 3 anchor=(0 0)
xoo.......
ooo.......
ooo.......
..........
..........

10 0 0 3 3 0 0 area -> [0 1 2 10 11 12 20 21 22]

Ex. 1b:source array: (height=5) width=10 anchor=(2 2)
subarea : height=3 width= 3 anchor=(2 2)
ooo.......
ooo.......
oox.......
..........
..........

10 2 2 3 3 2 2 area -> [0 1 2 10 11 12 20 21 22]

Ex. 1c:Note that anchor point may lie outside both
arrays' bounds:
source array: (height=5) width=10 anchor=(1 12)
subarea : height=3 width= 3 anchor=(1 12)
ooo.......
ooo....... x
ooo.......
..........
..........

10 1 12 3 3 1 12 area -> [0 1 2 10 11 12 20 21 22]

Ex. 2: source array: (height=6) width=15 anchor=(2 5)
subarea : height=4 width= 5 anchor=(1 3)
...............
..ooooo........
..oooxo........
..ooooo........
..ooooo........
...............

15 2 5 4 5 1 3 area -> [17 18 19 20 21
32 33 34 35 36
47 48 49 50 51
62 63 64 65 66]


File
sli/sliarray.cc
Diagnostics

May raise the following SLI interpreter errors:
StackUnderflowError
ArgumentTypeError

NO ARGUMENT RANGE CHECK IS PERFORMED.
The result may be useless if subarea is not
contained in the source array. Note that THIS
RESTRICTION DOES NOT APPLY TO FUNCTION "area2".

However anchor points may lie outside the array
bounds.

Note that the height of the source array is not used in computation
and does not appear in the parameter list

SeeAlso