libvips/doc/src/vimage.tex

\section{The \texttt{VImage} class}

The \verb+VImage+ class is a layer over the VIPS \verb+IMAGE+ type. It
automates almost all of the image creation and destruction issues that
complicate the C API, it automates error handling, and it provides a
convenient system for composing operations.

\subsection{Constructors}

There are two principal constructors for \verb+VImage+:

\begin{verbatim}
VImage::VImage( const char *name, 
  const char *mode = "r" );
VImage::VImage();
\end{verbatim}

The first form creates a new \verb+VImage+, linking it to the named file.
\verb+mode+ sets the mode for the file: it can take the following values:

\begin{description}

\item[\texttt{"r"}]
The named image file is opened read-only. This is the default mode.

\item[\texttt{"w"}]
A \verb+VImage+ is created which, when written to, will write pixels to disc
in the specified file. Any existing file of this name is deleted.

\item[\texttt{"t"}]
As the \verb'"w"' mode, but pixels written to the \verb+VImage+ will be saved
in a temporary memory buffer.

\item[\texttt{"p"}]
This creates a special `partial' image. Partial images represent
intermediate results, and are used to join VIPS operations together,
see~\pref{sec:compute}.

\item[\texttt{"rw"}]
As the \verb'"r"' mode, but the image is mapped into your address space
read-write. This mode is useful for paintbox-style
applications which need to directly modify an image. See \pref{sec:inplace}.

\end{description}

The second form of constructor is shorthand for:

\begin{verbatim}
VImage( "VImage:1", "p" )
\end{verbatim}

\noindent
It is used for representing intermediate results of computations.

Two further constructors are handy for wrapping \verb+VImage+ around existing
images.

\begin{verbatim}
VImage( void *buffer, 
  int width, int height, int bands, 
  TBandFmt format );
VImage( void *image );
\end{verbatim}

\noindent
The first constructor makes a \verb+VImage+ from an area of memory (perhaps
from another image processing system), and the second makes a \verb+VImage+
from an \verb+IMAGE+. 

In both these two cases, the VIPS C++ API does not assume responsibility
for the resources: it's up to you to make sure the buffer is freed.

The Python interface adds the usual \verb+frombuffer+ and
\verb+fromstring+ methods. 

\begin{verbatim}
VImage.fromstring (string, 
  width, height, bands, format) -> 
  VImage
\end{verbatim}

\begin{verbatim}
VImage.frombuffer (buffer, 
  width, height, bands, format) -> 
  VImage
\end{verbatim}

\noindent
Use \verb+fromstring+ to avoid worries about object lifetime, but you'll see a
lot of copies and high memory use. Use \verb+frombuffer+ for speed, but you
have to manage object lifetime yourself.

They are useful for moving images into VIPS from other image processing
libraries. There's also a utility function, \verb+vips_from_PIL_mode+, which
turns a PIL mode into a VIPS band, format, type triple.

\begin{verbatim}
VImage.vips_from_PIL_mode (mode) -> 
  (bands, format, type) 
\end{verbatim}

See also \verb+tobuffer+ and \verb+tostring+ below.

\subsection{File conversion}

VIPS can read and write a number of different file formats. Information about
file format conversion is taken from the filename. For example:

\begin{verbatim}
VImage jim( "fred.jpg" );
\end{verbatim}

\noindent
This will decompress the file \verb+fred.jpg+ to a memory buffer, wrap a VIPS
image around the buffer and build a reference to it called \verb+jim+.

Options are passed to the file format converters embedded in the filename. For
example:

\begin{verbatim}
VImage out( "jen.tif:deflate", "w" );
\end{verbatim}

\noindent
Writing to the descriptor \verb+out+ will cause a TIFF image to be written to
disc with deflate compression.

See the manual page for \verb+im_open(3)+ for details of all the file formats
and conversions available. See the man page for \verb+VipsFormat(3)+ for a
lower-level API which lets you control more of the detail of reading and
writing data and is more suitable for large files.

\subsection{Projection functions}

A set of member functions of \verb+VImage+ provide access to the fields in
the header:

\begin{verbatim}
int Xsize();
int Ysize();
int Bands();
TBandFmt BandFmt();
TCoding Coding();
TType Type();
float Xres();
float Yres();
int Length();
TCompression Compression();
short Level();
int Xoffset();
int Yoffset();
\end{verbatim}

\noindent
Where \verb+TBandFmt+, \verb+TCoding+, \verb+TType+ and \verb+TCompression+
are \verb+enum+s for the types in the VIPS file header. See
section~\pref{sec:header} for an explanation of all of these fields.

Two functions give access to the filename and history
fields maintained by the VIPS IO system.

\begin{verbatim}
char *filename();
char *Hist();
\end{verbatim}

You can get and set extra metadata fields with \verb+meta_get()+ and
\verb+meta_set()+. They read and write \verb+GValue+ objects, see 
\pref{sec:meta}.

\begin{verbatim}
void meta_set( const char *field, GValue *value );
void meta_get( const char *field, GValue *value_copy );
GType meta_get_type( const char *field );
\end{verbatim}

A set of convenience functions build on these two to provide accessors for
common types.

\begin{verbatim}
int meta_get_int( const char *field )
double meta_get_double( const char *field )
const char *meta_get_string( const char *field )
void *meta_get_area( const char *field )
void *meta_get_blob( const char *field, size_t *length ) 

void meta_set( const char *field, int value ) 
void meta_set( const char *field, double value )
void meta_set( const char *field, const char *value )
void meta_set( const char *field, 
	VCallback free_fn, void *value ) 
void meta_set( const char *field, 
	VCallback free_fn, void *value, size_t length ) 
\end{verbatim}

The \verb+image()+ member function provides access to the \verb+IMAGE+
descriptor underlying the C++ API. See the \pref{sec:appl} for details.

\begin{verbatim}
void *image();
\end{verbatim}

The \verb+data()+ member function returns a pointer to an array of pixel data
for the image. 

\begin{verbatim}
void *data() const;
\end{verbatim}

\noindent
This can be very slow and use huge amounts of RAM.

The Python interface adds \verb+tobuffer+ and \verb+tostring+. These
operations call \verb+data()+ to generate the image pixels and then either
copy it and return the copy as a string, or wrap the pixels up as a Python
buffer object.

Use \verb+tostring+ to avoid worries about object lifetime, but you'll see a
lot of copies and high memory use. Use \verb+tobuffer+ for speed, but you
have to manage object lifetime yourself.

They are useful for moving images from VIPS into other image processing
libraries. There's also a utility function, \verb+PIL_mode_from_vips+, which
makes a PIL mode from a VIPS image.

\begin{verbatim}
VImage.PIL_mode_from_vips (vips-image) -> 
  mode
\end{verbatim}

See also \verb+frombuffer+ and \verb+fromstring+ above.

\subsection{Assignment}

\verb+VImage+ defines copy and assignment, with reference-counted,
pointer-style semantics.  For example, if you write:

\begin{verbatim}
VImage fred( "fred.v" );
VImage jim( "jim.v" );

fred = jim;
\end{verbatim}

This will automatically close the file \verb+fred.v+, and make the variable
\verb+fred+ point to the image \verb+jim.v+ instead. Both \verb+jim+ and
\verb+fred+ now point to the same underlying image object. 

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

\subsection{Computing with \texttt{VImage}s}
\label{sec:compute}

All VIPS image processing operations are member functions of the \verb+VImage+
class. For example:

\begin{verbatim}
VImage fred( "fred.v" );
VImage jim( "jim.v" );

VImage result = fred.cos() + jim;
\end{verbatim}

Will apply \verb+im_costra()+ to \verb+fred.v+, making an image where each
pixel is the cosine of the corresponding pixel in \verb+fred.v+; then add that
image to \verb+jim.v+. Finally, the result will be held in \verb+result+.

VIPS is a demand-driven image processing system: when it computes expressions
like this, no actual pixels are calculated (although you can use the
projection functions on images --- \verb+result.BandFmt()+ for example).  When
you finally write the result to a file (or use some operation that needs pixel
values, such as \verb+min()+, find minimum value), VIPS evaluates all of the
operations you have called to that point in parallel. If you have more than one
CPU in your machine, the load is spread over the available processors. This
means that there is no limit to the size of the images you can process.

\pref{sec:packages} lists all of the VIPS packages. These general
rules apply:

\begin{itemize}

\item
VIPS operation names become C++ member function names by dropping the
\verb+im_+ prefix, and if present, the \verb+tra+ postfix, the \verb+const+
postfix and the \verb+_vec+ postfix. For example, the
VIPS operation \verb+im_extract()+ becomes \verb+extract()+, and
\verb+im_costra()+ becomes \verb+cos()+.

\item
The \verb+VImage+ object to which you apply the member function is the first
input image, the member function returns the first output. If there is no
image input, the member is declared \verb+static+.

For example, \verb+im_project(3)+ returns two images. You can call it from
Python like this:

\begin{verbatim}
hout = VImage.VImage ()
vout = im.project (hout)
\end{verbatim}

\noindent
In other words, \verb+.project()+ writes the second result to the 
\verb+VImage+ you pass as an argument.

\item
\verb+INTMASK+ and \verb+DOUBLEMASK+ types become \verb+VMask+ objects,
\verb+im_col_display+ types become \verb+VDisplay+ objects.

\item
Several C API functions can map to the same C++ API member. For example,
\verb+im_andimage+, \verb+im_andimage_vec+ and \verb+im_andimageconst+ all map
to the member \verb+andimage+. The API relies on overloading to
discriminate between these functions.

\end{itemize}

This part of the C++ API is generated automatically from the VIPS function
database, so it should all be up-to-date.

There are a set of arithmetic operators defined for your convenience. You can
generally write any arithmetic expression and include \verb+VImage+ in there.

\begin{verbatim}
VImage fred( "fred.v" );
VImage jim( "jim.v" );

Vimage v = int((fred + jim) / 2);
\end{verbatim}

\subsection{Writing results}

Once you have computed some result, you can write it to a file with the member
\verb+write()+. It takes the following forms:

\begin{verbatim}
VImage write( const char *name );
VImage write( VImage out );
VImage write();
\end{verbatim}

The first form simply writes the image to the named file. The second form
writes the image to the specified \verb+VImage+ object, for example:

\begin{verbatim}
VImage fred( "fred.v" );
VImage jim( "jim buffer", "t" );

Vimage v = (fred + 42).write( jim );
\end{verbatim}

\noindent
This creates a temporary memory buffer called \verb+jim+, and fills it with
the result of adding 42 to every pixel in \verb+fred.v+.

The final form of \verb+write()+ writes the image to a memory buffer, and
returns that.

\subsection{Type conversions}

Two type conversions are defined: you can cast \verb+VImage+ to a
\verb+VDMask+ and to a \verb+VIMask+.

\begin{verbatim}
operator VDMask();
operator VIMask();
\end{verbatim}

These operations are slow and need a lot of memory! Emergencies only.