HELP AWM_TO_REGIONS                         Jocelyn Paine  November 1992


This module exports a routine for marking regions within an AWM. You
can use it by doing
    lib awm_to_regions;


Introduction
------------

If you don't know what an AWM is, it will help to read HELP AWM
before going any further. The idea of regions is best shown by an
example:

    awm =>
    ** AWM:
         xk: -5 to 5;  yk: -5 to 5
         xbounds: -10 to 10;   ybounds: -10 to 10
         position: (0,0)
         forward: [0 1];   right: [1 0]
    ???     ???
    ???*****???
    ???     ???
      *   k  *
      *      *
      *  B   #
      *    * *
      *      *
    ???*****???
    ???     ???
    ???@    ???

    awm_to_regions( awm, `a`, procedure(c);1+c;endprocedure, true )
        -> regions;

    awm=>
    ** AWM:
         xk: -5 to 5;  yk: -5 to 5
         xbounds: -10 to 10;   ybounds: -10 to 10
         position: (0,0)
         forward: [0 1];   right: [1 0]
    ???eeeee???
    ???*****???
    ???ccccc???
    bb*ccckcc*d
    bb*cccccc*d
    bb*ccBccc#d
    bb*cccc*c*d
    bb*cccccc*d
    ???*****???
    ???aaaaa???
    ???@aaaa???

    regions==>
    ** [[101 [-2 5] [-1 5] [0 5] [1 5] [2 5]]
        [100 [5 -2] [5 -1] [5 0] [5 1] [5 2]]
        [99 [-2 -2]
            [-2 -1]
            <etc>
            [3 2]
            [2 3]]
        [98 [-5 -2]
            [-5 -1]
            <etc>
            [-4 -2]
            [-4 2]]
        [97 [-1 -5] [-2 -4] [-1 -4] [0 -5] [0 -4]
            [1 -5] [1 -4] [2 -5] [2 -4]]]

Essentially, within an AWM, awm_to_regions finds all the regions
(connected regions of blank squares, bounded by non-spaces or
undefineds), and replaces all the blanks in each with a unique
character. It also returns a list of these characters and the points
making up each region. The marked AWM can be used in various types of
analogical processing. For example, to find out what region an object is
in, you only need to look at the region markers neighbouring it.


Exported routines
-----------------

PUBLIC awm_to_regions( awm, first_reg, next_reg, keep ):

This routine marks awm in the way described above. first_reg must be a
character, to be used as the marker for the first region found.
next_reg must be a function which when applied to a region marker,
yields the next one. In the example above, this is done just by
adding one to it.

If keep is true, awm_to_regions returns a list of sublists. Each sublist
is of the form
    [ <region> <point1> <point2> ... ]
where <region> is that region's character, and <point1> etc are the
points within the region, as vecs (or lists: see HELP VEC).        

If keep is true, awm_to_regions just returns an integer, giving the
number of regions found.


Resetting an AWM
----------------

You can use the routine awm_replace from AWM.P to get rid of the region
markers. In the example above, the call

    awm_replace( awm, procedure(c);lvars c; c>=`a`;endprocedure, ` ` );

will replace any character whose ASCII code is that for `a` or greater,
with a space.
