# Command: area

NEST HelpDesk | Command Index | NEST Quick Reference

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:

- area2

Source:

    /opt/conda/conda-bld/nest_1524088722951/work/nest-2.14.0/sli/sliarray.cc

NEST HelpDesk | Command Index | NEST Quick Reference

© 2004 The NEST Initiative