aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/documentation.tex529
-rw-r--r--doc/space_mask.eps203
-rw-r--r--doc/space_mask.fig68
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
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-28 20:17:12 +0000