| \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 gauss_sep( 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. |