libvips/doc/src/vmask.tex

\section{The \texttt{VMask} class}

The \verb+VMask+ class is an abstraction over the VIPS \verb+DOUBLEMASK+ and
\verb+INTMASK+ types which gives convenient and safe representation of
matrices.

\verb+VMask+ has two sub-classes, \verb+VIMask+ and \verb+VDMask+. These
represent matrices of integers and doubles respectively.

\subsection{Constructors}

There are four constructors for \verb+VIMask+ and \verb+VDMask+:

\begin{verbatim}
VIMask( int xsize, int ysize );
VIMask( int xsize, int ysize, 
  int scale, int offset, ... );
VIMask( int xsize, int ysize, 
  int scale, int offset, 
  std::vector<int> coeff );
VIMask( const char *name );
VIMask();
VDMask( int xsize, int ysize );
VDMask( int xsize, int ysize, 
  double scale, double offset, ... );
VDMask( int xsize, int ysize, 
  double scale, double offset, 
  std::vector<double> coeff );
VDMask( const char *name );
VDMask();
\end{verbatim}

The first form creates an empty matrix, with the specified dimensions;
the second form initialises a matrix from a varargs list; the third form
sets the matrix from a vector of coefficients; the fourth from the named file. 
The final form makes a mask object with no contents yet.

The varargs constructors are not wrapped in Python --- use the vector
constructor instead. For example:

\begin{verbatim}
m = VMask.VIMask (3, 3, 1, 0, 
		  [-1, -1, -1,
		   -1,  8, -1,
		   -1, -1, -1])
\end{verbatim}

\subsection{Projection functions}

A set of member functions of \verb+VIMask+ provide access to the fields in
the matrix:

\begin{verbatim}
int xsize() const;
int ysize() const;
int scale() const;
int offset() const;
const char *filename() const;
\end{verbatim}

\verb+VDMask+ is the same, except that the \verb+scale()+ and \verb+offset()+
members return \verb+double+. \verb+VMask+ allows all operations that are
common to \verb+VIMask+ and \verb+VDMask+.

\subsection{Assignment}

\verb+VMask+ defines copy and assignment with pointer-style
semantics. You can write stuff like:

\begin{verbatim}
VIMask fred( "mask" );
VMask jim;

jim = fred;
\end{verbatim}

This reads the file \verb+mask+, noting a pointer to the mask in \verb+fred+.
It then makes \verb+jim+ also point to it, so \verb+jim+ and \verb+fred+ are
sharing the same underlying matrix values.  

Internally, a \verb+VMask+ object is just a pointer to a reference-counting
block, which in turn holds a pointer to the underlying VIPS \verb+MASK+ type.
You can therefore efficiently pass \verb+VMask+ objects to functions by
value, and return \verb+VMask+ objects as function results.

\subsection{Computing with \texttt{VMask}}

You can use \verb+[]+ to get at matrix elements, numbered left-to-right,
top-to-bottom. Alternatively, use \verb+()+ to address elements by $x,y$
position. For example:

\begin{verbatim}
VIMask fred( "mask" );

for( int i = 0; i < fred.xsize(); i++ )
    fred[i] = 12;
\end{verbatim}

\noindent
will set the first line of the matrix to 12, and:

\begin{verbatim}
VDMask fred( "mask" );

for( int x = 0; x < fred.xsize(); x++ )
    fred(x, x) = 12.0;
\end{verbatim}

\noindent
will set the leading diagonal to 12.

These don't work well in Python, so there's an extra member, \verb+get()+,
which will get an element by $x,y$ position.

\begin{verbatim}
x = mat.get (2, 4)
\end{verbatim}

See the member functions below for other operations on \verb+VMask+.

\subsection{\texttt{VIMask} operations}

The following operations are defined for \verb+VIMask+:

\begin{verbatim}
// Cast to VDMask and VImage
operator VDMask();
operator VImage();

// Build gaussian and log masks
static VIMask gauss( double, double );
static VIMask log( double, double );

// Rotate
VIMask rotate45();
VIMask rotate90();

// Transpose, invert, join and multiply
VDMask trn() ;
VDMask inv();
VDMask cat( VDMask );
VDMask mul( VDMask );
\end{verbatim}

\subsection{\texttt{VDMask} operations}

The following operations are defined for \verb+VDMask+:

\begin{verbatim}
// Cast to VIMask and VImage
operator VIMask();
operator VImage();

// Build gauss and log masks
static VDMask gauss( double, double );
static VDMask log( double, double );

// Rotate
VDMask rotate45();
VDMask rotate90(); 

// Scale to intmask
VIMask scalei();

// Transpose, invert, join and multiply
VDMask trn();
VDMask inv();
VDMask cat( VDMask );
VDMask mul( VDMask );
\end{verbatim}

\subsection{Output of masks}

You can output masks with the usual \verb+<<+ operator.