Implementation of the recently discussed spacemask spec. See the

doc/documentation.tex for details.

The existing mask grid-function (emask) has been retained for the
time being, until the excision related thorns can be brought up to
date with the new interface. These thorns should see no change in
their behaviour. In the meantime, the space_mask GF can be used
simultaneously via the new interfaces.


git-svn-id: http://svn.cactuscode.org/arrangements/CactusNumerical/SpaceMask/trunk@15 a491c6a4-70bf-4b89-8b36-d6c0cb1f094e

3 files changed, 787 insertions, 13 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 5376ec6..33cad43 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -8,8 +8,8 @@
 
 \begin{document}
 
-\title{SpaceMask}
-\author{Tom Goodale}
+\title{Using SpaceMask}
+\author{Denis Pollney}
 \date{$ $Date$ $}
 
 \maketitle
@@ -18,25 +18,528 @@
 % START CACTUS THORNGUIDE
 
 \begin{abstract}
-Provides a mask function for the spatial slice variables
+The SpaceMask thorn provides a grid function which can be used to
+store user-defined states at each grid point. Routines are provided
+for quickly setting and checking the mask states.
 \end{abstract}
 
-\section{Purpose}
+\section{The mask bit-field}
 
-This will provide two integer grid functions
+The mask is a grid function which can be used to assign a state to
+each point on the grid. It is used as a bit field, with different
+bits, or combinations of bits, assigned to represent various states.
+The mask is currently implemented as a CCTK\_INT8 grid function,
+providing 64 bits per point. Appropriate numbers of bits within
+the mask can be allocated to represent individual states of
+a given type.
 
-space\_mask
-space\_table\_field
+For instance, a programmer wants to record whether each point of the
+grid has \emph{state} ``interior'', ``excised'' or ``boundary''. The
+collection of these states is called a \emph{type}, and 2-bits of the
+mask (enough to represent the three possible states of the type) are
+allocated to hold this information. If an independent classification
+of points (ie. a new type) is required, bits are allocated to it from
+the remaining free bits in the mask. (See Figure \ref{fig:mask_bits}.)
 
-the first one will be a bitmask describing the point, with one bit
-indicating that there is extra data in a table the handle of which can be
-found in the corresponding point in the space\_table\_field.
+The SpaceMask thorn provides a set of routines for allocating bits
+within the mask, and for setting and checking the mask state at
+individual points.
 
-Thorns interested in the mask should inherit from this implementation.
+\begin{figure}
+  \centering
+  \includegraphics{space_mask.eps}
+  \caption{The \texttt{SpaceMask\_RegisterType()} function allocates
+  bits of the mask to a new ``type'' (eg. ``excision'' and ``colour''
+  in the figure). The number of bits that are allocated is determined
+  by the number of possible states of the given type.}
+  \label{fig:mask_bits}
+\end{figure}
 
-There may also be aliased query functions provided.
+\section{Using the mask}
 
-\section{Comments}
+A number of functions are provided for registering new types, and
+checking and setting mask values at a point. The interface to these
+functions differs slightly for C and Fortran90 code.
+
+\subsection{Accessing the mask from C Code}
+
+The following description describes the C interface for manipulating
+the mask. An example of code using these functions can be found in
+Appendix \ref{app:eg_C}.
+
+\subsubsection{Registering a new type}\label{sec:reg_C}
+
+Bits of the mask are allocated to a new type using the function:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+int SpaceMask\_RegisterType(char* \emph{type\_name}, int \emph{nstates},
+  char** \emph{state\_list})
+}
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{type\_name}] The name of the new type to be registered;
+  \item[\emph{nstates}] The number of states in the new type;
+  \item[\emph{state\_list}] A list of names, one for each state.
+\end{description}
+}
+}
+
+\noindent An appropriate number of bits of the mask are allocated to
+hold a unique value for the $n$ states specified by the \emph{nstates}
+argument. The registration must take place before the type can be
+used, so for instance, could be scheduled at CCTK\_STARTUP. New
+states can be added to an already allocated type using the function:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+  int SpaceMask\_AppendStatesToType(char* \emph{type\_name},
+  int \emph{nstates}, char** \emph{state\_list})
+}
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{type\_name}] The name of an already registered type;
+  \item[\emph{nstates}] The number of states to be added;
+  \item[\emph{state\_list}] A list of names, one for each of the new
+    states.
+\end{description}
+}}
+
+\noindent A number of new bits will be added to the specified type
+appropriate to hold the number of existing states plus the extra
+states. The allocated bits need not be contiguous within the mask.
+
+\subsubsection{Setting and checking mask states}
+
+The state of the mask at a given point is set using the function:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+void SpaceMask\_SetState(CCTK\_INT8* \emph{mask}, int \emph{point},
+  char* \emph{type\_name}, char* \emph{state})
+}
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{mask}] A pointer to the mask grid function;
+  \item[\emph{point}] The index of the point within the grid function
+    array;
+  \item[\emph{type\_name}] The name of the type containing the state;
+  \item[\emph{state\_name}] The particular state to be set.
+\end{description}
+}}
+
+The state of the mask at a given point can be checked using:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+int SpaceMask\_CheckState(CCTK\_INT8* \emph{mask}, int \emph{point},
+  char* \emph{type\_name}, char* \emph{state})
+}
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{mask}] A pointer to the mask grid function;
+  \item[\emph{point}] The index of the point within the grid function
+    array;
+  \item[\emph{type\_name}] The name of the type containing the state;
+  \item[\emph{state\_name}] The particular state to be compared.
+\end{description}
+}}
+
+The return value is 1 if the given \emph{state\_name} has been set at
+the point, or 0 otherwise.
+
+\subsubsection{Faster bitwise operators}
+
+The above mentioned functions for checking and setting the mask are
+rather inefficient, since they require strings to be compared at each
+point. A set of faster macros are provided which operate on the mask
+by performing bit operations directly. In order to use these
+functions, the bitmasks corresponding to the desired type and it's
+states need to be obtained using the following functions:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+CCTK\_INT8 SpaceMask\_GetTypeBits(char* \emph{type\_name})
+}\\
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{type\_name}] The type for which the bitmask is to be
+  determined.
+\end{description}
+}}
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+CCTK\_INT8 SpaceMask\_GetStateBits(char* \emph{type\_name},
+  char* \emph{state\_name})
+}
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{type\_name}] The type containing the state in question;
+  \item[\emph{state\_name}] The state whose bitmask is to be determined.
+\end{description}
+}}
+
+\noindent Each of these functions returns a CCTK\_INT which holds the
+bitmask corresponding to the given type or state. For example, if a
+given type uses three bits of the mask, the returned value could be
+the integer corresponding to the bitfield 001110000\ldots, where the
+location of 1s indicates the bits which have been allocated to the
+given type.
+
+The following macros have been defined for fast setting and checking
+of the mask by direct bitwise operations:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+void SpaceMask\_SetStateBits(CCTK\_INT8* \emph{mask}, int \emph{point},
+  CCTK\_INT8 \emph{type\_bits},\\\hspace*{10mm} CCTK\_INT8 \emph{state\_bits})
+}\\
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{mask}] A pointer to the mask grid function;
+  \item[\emph{point}] The index of the point within the grid function
+    array;
+  \item[\emph{type\_bits}] The bitmask corresponding to the required
+    type;
+  \item[\emph{state\_bits}] The bitmask corrsponding to the required
+    state;
+\end{description}
+}}
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+int SpaceMask\_CheckStateBits(CCTK\_INT8* \emph{mask}, int \emph{point},
+  CCTK\_INT8 \emph{type\_bits},\\\hspace*{10mm} CCTK\_INT8 \emph{state\_bits})
+}\\
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{mask}] A pointer to the mask grid function;
+  \item[\emph{point}] The index of the point within the grid function
+    array;
+  \item[\emph{type\_bits}] The bitmask corresponding to the required
+    type;
+  \item[\emph{state\_bits}] The bitmask corrsponding to the required
+    state;
+\end{description}
+}}
+
+\noindent The latter macro returns a 1 if the given state has been
+set, a 0 otherwise. The \emph{type\_bits} and \emph{state\_bits} can
+be obtained using the \texttt{SpaceMask\_Get*Bits} functions,
+described above.
+
+\subsection{Accessing the mask from Fortran90 Code}
+
+The following Fortran interfaces to the mask utilities apply only to
+Fortran90 code, since fast bitwise operations are not a part of the
+Fortran77 standard. An example of the use of the Fortran90 interface
+can be found in Appendix \ref{app:eg_F90}.
+
+\subsubsection{Registering a new type}
+
+Registration functions have not been implemented for the Fortran90
+interface, though they can easily be written in C by following the
+descriptions in Section \ref{sec:reg_C} and the example in Appendix
+\ref{app:eg_C}.
+
+\subsubsection{Setting and checking mask states}
+
+The mask states can be manipulated using the following functions:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+  SpaceMask\_SetState(CCTK\_INT8 \emph{mask(,,)}, int \emph{point}, 
+    character \emph{type\_name},\\\hspace*{10mm} character \emph{state\_name})
+}\\
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{mask}] A pointer to the mask grid function;
+  \item[\emph{point}] The index of the point within the grid function
+    array;
+  \item[\emph{type\_name}] The name of the type containing the state;
+    type;
+  \item[\emph{state\_name}] The name of the state to be set.
+\end{description}
+}}
+
+\noindent The value of the \emph{mask} variable is changed to turn on
+the specified state at the point.
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+  SpaceMask\_CheckState(CCTK\_INT \emph{check}, CCTK\_INT8 \emph{mask(,,)},
+    int \emph{point},\\\hspace*{10mm} character \emph{type\_name},
+    character \emph{state\_name})
+}\\
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{check}] A variable which is set to 1 if the requested
+    state has been set;
+  \item[\emph{mask}] A pointer to the mask grid function;
+  \item[\emph{point}] The index of the point within the grid function
+    array;
+  \item[\emph{type\_name}] The name of the type containing the state;
+    type;
+  \item[\emph{state\_name}] The name of the state to be checked.
+\end{description}
+}}
+
+\subsubsection{Faster bitwise operators}
+
+As in the C interface, alternative bitwise operators have been defined
+in order to more quickly operate on the mask at a point. In order to
+use these functions, the bitmasks corresponding to the type and states
+in question must first be obtained using the following functions:
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+  SpaceMask\_GetTypeBits(CCTK\_INT8 \emph{type\_bits},
+    character \emph{type\_name})
+}
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{type\_bits}] A variable which will be set to the bitmask of
+    the requested type;
+  \item[\emph{type\_name}] A character string naming the type.
+\end{description}
+}}
+
+\indent\parbox{\linewidth}{
+\vspace{\baselineskip}\noindent\texttt{
+  SpaceMask\_GetStateBits(CCTK\_INT8 \emph{state\_bits},
+    character \emph{type\_name},\\\hspace*{10mm} character \emph{state\_name})
+}\\
+\hspace*{10mm}\parbox{\linewidth}{
+\begin{description}
+  \item[\emph{state\_bits}] A variable which will be set to the bitmask of
+    the requested state;
+  \item[\emph{type\_name}] A character string naming the type
+    containing the state;
+  \item[\emph{type\_name}] A character string naming the state.
+\end{description}
+}}
+
+\noindent Once the bitmasks for the type and state have been obtained,
+the following macros can be used directly:
+
+\vspace{\baselineskip}\noindent\texttt{
+  SpaceMask\_SetStateBitsF90(mask, i, j, k, type\_bits, state\_bits)
+}\\
+
+\noindent This macro sets the value of the mask at the index $(i,j,k)$
+to the given state. It doesn't have a return value, and can be used
+directly inline (without a Fortran `call').
+
+\vspace{\baselineskip}\noindent\texttt{
+  SpaceMask\_CheckStateBitsF90(mask, i, j, k, type\_bits, state\_bits)
+}\\
+
+\noindent A value of `\texttt{.true.}' is returned if the given state
+has been set, or `\texttt{.false.}' otherwise. The macro can be used
+directly in Fortran boolean expressions, as in the examples in
+Appendix \ref{app:eg_F90}.
+
+
+\section{Notes}
+
+A proposal exists to provide a more versatile solution by allowing
+tables to be associated with each grid point. This could be
+implemented using the existing standard outlined here through the
+addition of an additional integer grid function
+
+\texttt{space\_table\_field}
+
+A bit of the existing \texttt{space\_mask} would be allocated to
+indicate whether or not a table has been associated with the given
+point. If so, then the corresponding point in the
+\texttt{space\_table\_field} would hold the table handle.
+
+
+\section{Acknowledgements}
+
+Thanks to Jonathan Thornburg, Tom Goodale, and Erik Schnetter for
+helpful comments on the original specification. Useful implementation
+of the mask required grid symmetries to work for integer grid
+functions. This was done by Thomas Radke. Peter Diener helped with the
+coding of the Fortran90 bitwise operators.
+
+\pagebreak
+\appendix
+\section{Example: C code}\label{app:eg_C}
+
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_Arguments.h"
+#include "cctk_Parameters.h"
+
+#include "SpaceMask.h"
+
+/*
+ * Register a mask type with three states.
+ */
+void Eg_RegisterMask (void)
+{
+  char *state_list_excision[3] = {"normal", "excise", "boundary"};
+
+  SpaceMask_RegisterType("excision", 3, state_list_excision);
+
+  return;
+}
+
+/*
+ * Set the mask to the ``normal'' state at each point using the
+ * slower name-reference function. See below for an example using
+ * the faster bitwise operator to check the mask states.
+ */
+void Eg_SetMaskStates (CCTK_ARGUMENTS)
+{
+  DECLARE_CCTK_ARGUMENTS
+  DECLARE_CCTK_PARAMETERS
+
+  int i, j, k, ijk;
+
+  for (k=0; k<cctk_lsh[2]; ++k)
+  {
+    for (j=0; j<cctk_lsh[1]; ++j)
+    {
+      for (i=0; i<cctk_lsh[0]; ++i)
+      {
+	ijk = CCTK_GFINDEX3D(cctkGH, i, j, k);
+	
+	SpaceMask_SetState(space_mask, ijk, \"excision\", \"normal\");
+      }
+    }
+  }
+  return;
+}
+
+/*
+ * Check which of the points of the mask have been set to the
+ * ``boundary'' state using the bitwise macro.
+ */
+void Eg_CheckMaskStates (CCTK_ARGUMENTS)
+{
+  DECLARE_CCTK_ARGUMENTS
+  DECLARE_CCTK_PARAMETERS
+
+  int i, j, k, ijk;
+
+  CCTK_INT8 excision_mask;
+  CCTK_INT8 boundary_mask;
+
+  excision_mask = SpaceMask_GetTypeBits(\"excision\");
+  boundary_mask = SpaceMask_GetStateBits(\"boundary\");
+
+  for (k=0; k<cctk_lsh[2]; ++k)
+  {
+    for (j=0; j<cctk_lsh[1]; ++j)
+    {
+      for (i=0; i<cctk_lsh[0]; ++i)
+      {
+	ijk = CCTK_GFINDEX3D(cctkGH, i, j, k);
+
+	if (SpaceMask_CheckStateBits(space_mask, ijk, excision_mask,
+                                     boundary_mask))
+        {
+	  CCTK_VINFO(CCTK_THORNSTRING, 
+                     \"Point (%d,%d,%d) is a boundary point.\n\",
+                     i, j, k);
+	}
+      }
+    }
+  }
+  return;
+}
+\end{verbatim}
+
+
+\section{Example: Fortran90 code}\label{app:eg_F90}
+
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_Arguments.h"
+#include "cctk_Parameters.h"
+
+#include "SpaceMask.h"
+
+!
+! Sets each point of the mask to the 'normal' state. Here, 'normal'
+! is one of the states of the 'excision' type, which should have
+! been registered previously using the C SpaceMask_RegisterType()
+! function.
+!
+subroutine Eg_SetStateByName(CCTK_ARGUMENTS)
+  implicit none
+
+  integer ni, nj, nk
+  integer i, j, k, ijk
+
+  ni = cctk_lsh(1)
+  nj = cctk_lsh(2)
+  nk = cctk_lsh(3)
+
+  do k=1,nk
+     do j=1,nj
+        do i=1,ni
+           
+           ijk = (i-1) + ni*((j-1) + nj*(k-1))
+
+           call SpaceMask_SetState(space_mask, ijk, "excision", "normal")
+  
+        end do
+     end do
+  end do
+
+end subroutine Eg_SetStateByName
+
+!
+! Sets the mask values within a radius of 1 to the 'excise' state,
+! then does a check of the state of each point.  The bitwise macros
+! are used in this case for greater efficiency in setting/checking
+! the mask.
+!
+subroutine Eg_SetExcisedRegionByBitmask(CCTK_ARGUMENTS)
+  implicit none
+
+  integer ni, nj, nk
+  integer i, j, k, ijk
+
+  CCTK_INT8 type_bits, excised
+
+  ni = cctk_lsh(1)
+  nj = cctk_lsh(2)
+  nk = cctk_lsh(3)
+
+  call SpaceMask_GetTypeBits(type_bits, "excision")
+  call SpaceMask_GetStateBits(excised, "excision", "excised")
+
+  do k=1,nk
+     do j=1,nj
+        do i=1,ni
+
+           if (r(i,j,k).lt.1.d0) then
+              SpaceMask_SetStateBitsF90(space_mask, i, j, k, type_bits, &
+                   excised)
+           end if
+
+        end do
+     end do
+  end do
+
+  do k=1,nk
+     do j=1,nj
+        do i=1,ni
+           if (SpaceMask_CheckStateBitsF90(space_mask, i, j, k, type_bits, &
+                excised)) then
+              write(*,*) "The point (", i, j, k, ") has been excised."
+           end if
+        end do
+     end do
+  end do
+
+end subroutine Eg_SetExcisedRegionByBitmask
+\end{verbatim}
 
 % Do not delete next line
 % END CACTUS THORNGUIDE
diff --git a/doc/space_mask.eps b/doc/space_mask.eps
new file mode 100644
index 0000000..a9b2c62
--- /dev/null
+++ b/doc/space_mask.eps
@@ -0,0 +1,203 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: space_mask.eps
+%%Creator: fig2dev Version 3.2 Patchlevel 3d
+%%CreationDate: Thu Nov 14 11:23:42 2002
+%%For: dp@nbdell15 (Denis Pollney,,,)
+%%BoundingBox: 0 0 400 242
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 242 moveto 0 0 lineto 400 0 lineto 400 242 lineto closepath clip newpath
+-55.3 491.8 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% Polyline
+15.000 slw
+n 7200 4275 m 900 4275 l 900 4725 l
+ 7200 4725 l gs col0 s gr 
+% Polyline
+n 900 4275 m 1350 4275 l 1350 4725 l 900 4725 l
+ cp gs col6 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 1350 4275 m 1800 4275 l 1800 4725 l 1350 4725 l
+ cp gs col6 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 1800 4275 m 2250 4275 l 2250 4725 l 1800 4725 l
+ cp gs col3 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 2250 4275 m 2700 4275 l 2700 4725 l 2250 4725 l
+ cp gs col3 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 2700 4275 m 3150 4275 l 3150 4725 l 2700 4725 l
+ cp gs col3 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 3150 4275 m 3600 4275 l 3600 4725 l 3150 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 3600 4275 m 4050 4275 l 4050 4725 l 3600 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 4050 4275 m 4500 4275 l 4500 4725 l 4050 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 4500 4275 m 4950 4275 l 4950 4725 l 4500 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 4950 4275 m 5400 4275 l 5400 4725 l 4950 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 5400 4275 m 5850 4275 l 5850 4725 l 5400 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 5850 4275 m 6300 4275 l 6300 4725 l 5850 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 6300 4275 m 6750 4275 l 6750 4725 l 6300 4725 l
+ cp gs col0 s gr 
+% Polyline
+n 1485 5535 m 3420 5535 l 3420 6885 l 1485 6885 l
+ cp gs col0 s gr 
+% Polyline
+n 4140 5535 m 6030 5535 l 6030 7785 l 4140 7785 l
+ cp gs col0 s gr 
+% Polyline
+n 1125 4725 m 1125 4950 l
+ 1575 4950 l gs col0 s gr 
+% Polyline
+n 1575 4725 m
+ 1575 5535 l gs col0 s gr 
+% Polyline
+n 2025 4725 m 2025 4950 l 4230 4950 l
+ 4230 5535 l gs col0 s gr 
+% Polyline
+n 2475 4725 m
+ 2475 4950 l gs col0 s gr 
+% Polyline
+n 2925 4725 m
+ 2925 4950 l gs col0 s gr 
+% Polyline
+n 1485 5535 m 3420 5535 l 3420 5940 l 1485 5940 l
+ cp gs col6 1.00 shd ef gr gs col0 s gr 
+% Polyline
+n 4140 5535 m 6030 5535 l 6030 5895 l 4140 5895 l
+ cp gs col3 1.00 shd ef gr gs col0 s gr 
+/Helvetica-Bold ff 210.00 scf sf
+1575 6165 m
+gs 1 -1 sc (00 = "normal") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+1575 6420 m
+gs 1 -1 sc (01 = "excised") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+1575 6705 m
+gs 1 -1 sc (10 = "boundary") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 6165 m
+gs 1 -1 sc (000 = "black") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 6420 m
+gs 1 -1 sc (001 = "red") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 6675 m
+gs 1 -1 sc (010 = "blue") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 6930 m
+gs 1 -1 sc (011 = "green") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 7185 m
+gs 1 -1 sc (100 = "yellow") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 7440 m
+gs 1 -1 sc (101 = "orange") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 7695 m
+gs 1 -1 sc (110 = "white") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+4275 5805 m
+gs 1 -1 sc (type: "colour") col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+900 4140 m
+gs 1 -1 sc (space_mask) col0 sh gr
+/Helvetica-Bold ff 210.00 scf sf
+1575 5805 m
+gs 1 -1 sc (type: "excision") col0 sh gr
+$F2psEnd
+rs
diff --git a/doc/space_mask.fig b/doc/space_mask.fig
new file mode 100644
index 0000000..920d8ed
--- /dev/null
+++ b/doc/space_mask.fig
@@ -0,0 +1,68 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 4
+	 7200 4275 900 4275 900 4725 7200 4725
+2 2 0 2 0 6 50 0 20 0.000 0 0 -1 0 0 5
+	 900 4275 1350 4275 1350 4725 900 4725 900 4275
+2 2 0 2 0 6 50 0 20 0.000 0 0 -1 0 0 5
+	 1350 4275 1800 4275 1800 4725 1350 4725 1350 4275
+2 2 0 2 0 3 50 0 20 0.000 0 0 -1 0 0 5
+	 1800 4275 2250 4275 2250 4725 1800 4725 1800 4275
+2 2 0 2 0 3 50 0 20 0.000 0 0 -1 0 0 5
+	 2250 4275 2700 4275 2700 4725 2250 4725 2250 4275
+2 2 0 2 0 3 50 0 20 0.000 0 0 -1 0 0 5
+	 2700 4275 3150 4275 3150 4725 2700 4725 2700 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 3150 4275 3600 4275 3600 4725 3150 4725 3150 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 3600 4275 4050 4275 4050 4725 3600 4725 3600 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 4050 4275 4500 4275 4500 4725 4050 4725 4050 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 4500 4275 4950 4275 4950 4725 4500 4725 4500 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 4950 4275 5400 4275 5400 4725 4950 4725 4950 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 5400 4275 5850 4275 5850 4725 5400 4725 5400 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 5850 4275 6300 4275 6300 4725 5850 4725 5850 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 6300 4275 6750 4275 6750 4725 6300 4725 6300 4275
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 1485 5535 3420 5535 3420 6885 1485 6885 1485 5535
+2 2 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 5
+	 4140 5535 6030 5535 6030 7785 4140 7785 4140 5535
+2 1 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 3
+	 1125 4725 1125 4950 1575 4950
+2 1 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 2
+	 1575 4725 1575 5535
+2 1 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 4
+	 2025 4725 2025 4950 4230 4950 4230 5535
+2 1 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 2
+	 2475 4725 2475 4950
+2 1 0 2 0 6 50 0 -1 0.000 0 0 -1 0 0 2
+	 2925 4725 2925 4950
+2 2 0 2 0 6 50 0 20 0.000 0 0 -1 0 0 5
+	 1485 5535 3420 5535 3420 5940 1485 5940 1485 5535
+2 2 0 2 0 3 50 0 20 0.000 0 0 -1 0 0 5
+	 4140 5535 6030 5535 6030 5895 4140 5895 4140 5535
+4 0 0 50 0 18 14 0.0000 4 165 1425 1575 6165 00 = "normal"\001
+4 0 0 50 0 18 14 0.0000 4 165 1485 1575 6420 01 = "excised"\001
+4 0 0 50 0 18 14 0.0000 4 210 1710 1575 6705 10 = "boundary"\001
+4 0 0 50 0 18 14 0.0000 4 165 1380 4275 6165 000 = "black"\001
+4 0 0 50 0 18 14 0.0000 4 165 1170 4275 6420 001 = "red"\001
+4 0 0 50 0 18 14 0.0000 4 165 1275 4275 6675 010 = "blue"\001
+4 0 0 50 0 18 14 0.0000 4 210 1425 4275 6930 011 = "green"\001
+4 0 0 50 0 18 14 0.0000 4 210 1470 4275 7185 100 = "yellow"\001
+4 0 0 50 0 18 14 0.0000 4 210 1560 4275 7440 101 = "orange"\001
+4 0 0 50 0 18 14 0.0000 4 165 1365 4275 7695 110 = "white"\001
+4 0 0 50 0 18 14 0.0000 4 210 1470 4275 5805 type: "colour"\001
+4 0 0 50 0 18 14 0.0000 4 210 1275 900 4140 space_mask\001
+4 0 0 50 0 18 14 0.0000 4 210 1650 1575 5805 type: "excision"\001