# area

Name:
`area - Return array of indices defining a 2d subarea of a 2d array.`
Synopsis:
```   source_width source_anchor_y source_anchor_x    area_height   area_width   area_anchor_y   area_anchor_x    area -> [1d-indices]
```
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]
```
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.)
```
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
```
References:
```(TO BE DONE: NEST layer indexing conventions)
```
Author:
```Ruediger Kupper
```
SeeAlso: Source:
`/home/graber/work-nest/nest-git/nest-simulator/sli/sliarray.cc`