sergiotarxz/libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

stuff

Browse Source
This commit is contained in:
John Cupitt 2009-03-27 17:23:11 +00:00
parent 47dec2610f
commit 1160f6a4b7
14 changed files with 343 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

@ -1,5 +1,6 @@
25/3/09 started 7.18.0
- revised version numbers
- updated vipsmanual
6/3/09 started 7.17.3
- revised nohalo

12
TODO
View File

@ -1,17 +1,21 @@
- im_rank.3 has a note about a black border, argh
any other references to this?
- VipsFormat.3 man page should list all formats, since eg. radiance does not
have a separate im_rad2vips page
also matlab read
- wrap im_gauss_mask_line or whatever it's called in C++/Python?
- need man pages for im_affinei, im_affinei_all
page for VipsInterpolate.3? along the lines of VipsFormat
- read through docs for 7.18 stuff
- Mention vips --list-classes or whatever in VipsFormat man page
:set spell
- update function list in refs
also in VipsInterpolate
WONTFIX for 7.18
================

4
doc/src/applintro.tex
View File

@ -2,7 +2,7 @@
\mylabel{sec:appl}
This chapter explains how to call VIPS functions from C programs. It does not
explain how to write new image processing operations (See \pref{sec:oper}),
explain how to write new image processing operations (see \pref{sec:oper}),
only how to call the ones that VIPS provides. If you want to call VIPS
functions from C++ programs, you can either use the interface described here
or you can try out the much nicer C++ interface described in \pref{sec:cpp}.
@ -26,7 +26,7 @@ example% man im_extract
\noindent
to get an explanation of the \verb+im_extract()+ function.
All the comand-line vips operations will print help text too. For example:
All the command-line VIPS operations will print help text too. For example:
\begin{verbatim}
example% vips im_extract

20
doc/src/format.tex
View File

@ -1,11 +1,11 @@
\section{Image formats}
\label{sec:format}
VIPS has a simple system for adding support for new image file formats.
You can ask VIPS to find a format to load a file with
or to select a image file writer based on a filename. Convenience functions
copy a file to an \verb+IMAGE+, or an \verb+IMAGE+ to a file. New formats may
be added to VIPS by simply defining a new subclass of \verb+VipsFormat+.
VIPS has a simple system for adding support for new image file formats.
You can ask VIPS to find a format to load a file with or to select a image
file writer based on a filename. Convenience functions copy a file to an
\verb+IMAGE+, or an \verb+IMAGE+ to a file. New formats may be added to
VIPS by simply defining a new subclass of \verb+VipsFormat+.
This is a parallel API to \verb+im_open()+, see \pref{sec:open}. The
format system is useful for images which are large or slow to open,
@ -42,16 +42,6 @@ version is one indicating that the file can be opened lazily
\end{itemize}
A switch to the \verb+vips+ command-line program is handy for listing the
supported formats. Try:
\begin{verbatim}
vips --list classes
\end{verbatim}
\noindent
And look for subclasses of \verb+VipsFormat+.
\subsection{The format class}
The interface to the format system is defined by the abstract base class

81
doc/src/func.tex
View File

@ -1,5 +1,8 @@
\section{Function dispatch and plug-ins}
(This chapter is on the verge of being deprecated. We have started building a
replacement based on \verb+GObject+, see \pref{sec:object}.)
As image processing libraries increase in size it becomes progressively more
difficult to build applications which present the operations the library
offers to the user. Every time a new operation is added, every user interface
@ -13,7 +16,7 @@ simply interrogate the database and present what they find to the user.
The operation database is extensible. You can define new operations, and even
new types, and add them to VIPS. These new operations will then automatically
appear in all VIPS user interfaces with no extra programming effort. Plugins
can extend the database at runtime: when VIPS starts, it loads all the plugin
can extend the database at runtime: when VIPS starts, it loads all the plugins
in the VIPS library area.
\subsection{Simple plugin example}
@ -84,50 +87,66 @@ macros available are listed in table~\ref{tab:type}.
Macro & Meaning &
\texttt{im\_object} has type \\
\hline
\texttt{IM\_INPUT\_IMAGEVEC} & Vector of input images &
\texttt{IMAGE **} \\
\texttt{IM\_INPUT\_IMAGE} & Input image &
\texttt{IMAGE *} \\
\texttt{IM\_OUTPUT\_IMAGE} & Output image &
\texttt{IMAGE *} \\
\texttt{IM\_RW\_IMAGE} & Read-write image &
\texttt{IMAGE *} \\
\texttt{IM\_INPUT\_INT} & Input int &
\texttt{int *} \\
\texttt{IM\_INPUT\_INTVEC} & Input vector of int &
\texttt{im\_intvec\_object *} \\
\texttt{IM\_INPUT\_IMASK} & Input int array &
\texttt{im\_mask\_object *} \\
\texttt{IM\_OUTPUT\_INT} & Output int &
\texttt{int *} \\
\texttt{IM\_INPUT\_INTVEC} & Output vector of int &
\texttt{im\_intvec\_object *} \\
\texttt{IM\_OUTPUT\_IMASK} & Output int array to file &
\texttt{im\_mask\_object *} \\
\texttt{IM\_INPUT\_DOUBLE} & Input double &
\texttt{double *} \\
\texttt{IM\_INPUT\_DOUBLEVEC} & Input vector of double &
\texttt{im\_realvec\_object *} \\
\texttt{IM\_INPUT\_INTVEC} & Input vector of int &
\texttt{im\_intvec\_object *} \\
\texttt{IM\_OUTPUT\_DOUBLE} & Output double &
\texttt{double *} \\
\texttt{IM\_INPUT\_INT} & Input int &
\texttt{int *} \\
\texttt{IM\_OUTPUT\_INT} & Output int &
\texttt{int *} \\
\texttt{IM\_INPUT\_STRING} & Input string &
\texttt{char *} \\
\texttt{IM\_OUTPUT\_STRING} & Output string &
\texttt{char *} \\
\texttt{IM\_INPUT\_DISPLAY} & Input display &
\texttt{im\_col\_display *} \\
\texttt{IM\_OUTPUT\_DISPLAY} & Output display &
\texttt{im\_col\_display *} \\
\texttt{IM\_OUTPUT\_COMPLEX} & Output complex &
\texttt{double *} \\
\texttt{IM\_INPUT\_DMASK} & Input double array &
\texttt{im\_mask\_object *} \\
\texttt{IM\_OUTPUT\_DOUBLE} & Output double &
\texttt{double *} \\
\texttt{IM\_OUTPUT\_DOUBLEVEC} & Output vector of double &
\texttt{im\_realvec\_object *} \\
\texttt{IM\_OUTPUT\_DMASK} & Output double array to file &
\texttt{im\_mask\_object *} \\
\texttt{IM\_OUTPUT\_DMASK\_STATS}& Output double array to screen &
\\
\texttt{IM\_INPUT\_IMASK} & Input int array &
\texttt{im\_mask\_object *} \\
\texttt{IM\_OUTPUT\_IMASK} & Output int array to file &
\texttt{im\_mask\_object *} \\
\texttt{IM\_OUTPUT\_COMPLEX} & Output complex &
\texttt{double *} \\
\texttt{IM\_INPUT\_STRING} & Input string &
\texttt{char *} \\
\texttt{IM\_OUTPUT\_STRING} & Output string &
\texttt{char *} \\
\texttt{IM\_INPUT\_IMAGE} & Input image &
\texttt{IMAGE *} \\
\texttt{IM\_INPUT\_IMAGEVEC} & Vector of input images &
\texttt{IMAGE **} \\
\texttt{IM\_OUTPUT\_IMAGE} & Output image &
\texttt{IMAGE *} \\
\texttt{IM\_RW\_IMAGE} & Read-write image &
\texttt{IMAGE *} \\
\texttt{IM\_INPUT\_DISPLAY} & Input display &
\texttt{im\_col\_display *} \\
\texttt{IM\_OUTPUT\_DISPLAY} & Output display &
\texttt{im\_col\_display *} \\
\texttt{IM\_INPUT\_GVALUE} & Input GValue &
\texttt{GValue *} \\
\texttt{IM\_OUTPUT\_GVALUE} & Output GValue &
\texttt{GValue *} \\
\texttt{IM\_INPUT\_INTERPOLATE} & Input VipsInterpolate &
\texttt{VipsInterpolate *} \\
\hline
\end{tabular}
\end{center}

76
doc/src/interpolate.tex
View File

@ -14,7 +14,7 @@ typedef void (*VipsInterpolateMethod)( VipsInterpolate *,
\end{verbatim}
\noindent
Given the set of input pixels \verb+in+, it has to calculate a value for the
given the set of input pixels \verb+in+, it has to calculate a value for the
fractional position $(x, y)$ and write this value to the memory pointed to by
\verb+out+.
@ -43,16 +43,6 @@ NULL and just set the int value \verb+window_size+.
\end{itemize}
A switch to the \verb+vips+ command-line program is handy for listing the
supported interpolators. Try:
\begin{verbatim}
vips --list classes
\end{verbatim}
\noindent
And look for subclasses of \verb+VipsInterpolate+.
\subsection{A sample interpolator}
As an example, \fref{fg:newinterpolator} shows how to register a new
@ -61,20 +51,27 @@ interpolator in a plugin.
\begin{fig2}
\begin{verbatim}
// This interpolator adds no new members.
typedef VipsInterpolate VipsInterpolateMyinterpolator;
typedef VipsInterpolateClass VipsInterpolateMyinterpolator;
typedef VipsInterpolate Myinterpolator;
typedef VipsInterpolateClass MyinterpolatorClass;
G_DEFINE_TYPE( Myinterpolator, myinterpolator, VIPS_TYPE_INTERPOLATE );
static void
vips_interpolate_myinterpolator_interpolate( VipsInterpolate *interpolate,
myinterpolator_interpolate( VipsInterpolate *interpolate,
PEL *out, REGION *in, double x, double y )
{
VipsInterpolateBilinearClass *class =
VIPS_INTERPOLATE_BILINEAR_GET_CLASS( interpolate );
MyinterpolatorClass *class =
MYINTERPOLATOR_GET_CLASS( interpolate );
/* Nearest-neighbor.
*/
memcpy( out,
IM_REGION_ADDR( in, floor( x ), floor( y ) ),
IM_IMAGE_SIZEOF_PEL( in->im ) );
}
static void
vips_interpolate_myinterpolator_class_init(
VipsInterpolateMyinterpolatorClass *class )
myinterpolator_class_init( MyinterpolatorClass *class )
{
VipsObjectClass *object_class = (VipsObjectClass *) class;
VipsInterpolateClass *interpolate_class = (VipsInterpolateClass *) class;
@ -82,29 +79,56 @@ vips_interpolate_myinterpolator_class_init(
object_class->nickname = "myinterpolator";
object_class->description = _( "My interpolator" );
interpolate_class->interpolate = my_interpolate;
interpolate_class->interpolate = myinterpolator_interpolate;
}
static void
vips_interpolate_myinterpolate_init( VipsInterpolateMyinterpolate *object )
myinterpolate_init( Myinterpolate *object )
{
}
G_DEFINE_TYPE( VipsInterpolateMyinterpolator, vips_interpolate_myinterpolator,
VIPS_TYPE_INTERPOLATE );
char *
g_module_check_init( GModule *self )
{
// register the type
vips_format_myformat_get_type();
myinterpolator_get_type();
}
\end{verbatim}
\caption{Registering an interpolator in a plugin}
\label{fg:newinterpolator}
\end{fig2}
\subsection{Passing an interpolator to a VIPS operation}
\subsection{Writing a VIPS operation that takes an interpolator as an argument}
Operations just take a \verb+VipsInterpolate+ as an argument, for example:
\begin{verbatim}
int im_affinei_all( IMAGE *in, IMAGE *out,
VipsInterpolate *interpolate,
double a, double b, double c, double d,
double dx, double dy );
\end{verbatim}
To use the interpolator, use \verb+vips_interpolate()+:
\begin{verbatim}
void vips_interpolate( VipsInterpolate *interpolate,
PEL *out, REGION *in, double x, double y );
\end{verbatim}
\noindent
This looks up the interpolate method for the object and calls it for you.
You can save the cost of the lookup in an inner loop with
\verb+vips_interpolate_get_method()+:
\begin{verbatim}
VipsInterpolateMethod
vips_interpolate_get_method(
VipsInterpolate *interpolate );
\end{verbatim}
\subsection{Passing an interpolator to a VIPS operation}
You can build an instance of a \verb+VipsInterpolator+ with
the \verb+vips_object_*()+ family of functions, see \pref{sec:object}.

77
doc/src/iosys.tex
View File

@ -1,13 +1,12 @@
\section{Core C API}
VIPS is
built on top of several other libraries, two of which, glib and gobject, are
exposed at various points in the C API.
VIPS is built on top of several other libraries, two of which, glib and
gobject, are exposed at various points in the C API.
You can read up on glib at the GTK+ website:
\begin{verbatim}
http://www.gtk.org/api
http://www.gtk.org
\end{verbatim}
There's also an excellent book by Matthias Warkus, \emph{The Official
@ -168,6 +167,15 @@ Descriptors are created with \verb+im_open()+. You can also read images with
the format system: see \pref{sec:format}. The two APIs are complimentary,
though \verb+im_open()+ is more useful.
At the command-line, try:
\begin{verbatim}
$ vips --list classes
\end{verbatim}
/noindent
to see a list of all the supported file formats.
\verb+im_open()+ takes a file name and a string representing the mode with
which the descriptor is to be opened:
@ -187,10 +195,8 @@ different byte ordering, \verb+im_open()+ will automatically convert it to
native VIPS format. If the underlying file does not support random access
(JPEG, for example), the entire file will be converted in memory.
VIPS can read images in TIFF, JPEG, PPM/\-PGM/\-PBM, PNG and VIPS
format, all in both big- and little-endian varieties. You can control the
details of the conversion with extra characters embedded in the filename. For
example:
VIPS can read images in many file formats. You can control the details of
the conversion with extra characters embedded in the filename. For example:
\begin{verbatim}
fred = im_open( "fred.tif:2",
@ -200,25 +206,15 @@ fred = im_open( "fred.tif:2",
\noindent
will read page 2 of a multi-page TIFF. See the man pages for details.
If VIPS has been built with libMagick, it can also read any of the 80 or so
libMagick-supported image file formats.
\item[\texttt{"w"}]
An \verb+IMAGE+ descriptor is created which, when written to, will write
pixels to disc in the specified file.
pixels to disc in the specified file. Any existing file of that name is
deleted.
VIPS looks at the filename suffix to determine the save format. If there
is no suffix, or the filename ends in \verb+".v"+, the image is written
in VIPS native format.
If the filename ends in \verb+".tif"+ or \verb+".tiff"+, the image
is written with \verb+im_vips2tiff()+. If the filename ends in
\verb+".jpg"+, \verb+".jpeg"+ or \verb+".jpe"+, the image is written with
\verb+im_vips2jpg()+. If the filename ends with \verb+".pbm"+, \verb+".pgm"+
or \verb+".ppm"+, the image is written using \verb+im_vips2ppm()+.
If the filename ends with \verb+".png"+, the image is written using
\verb+im_vips2png()+. Case is not considered when testing the suffix.
If you want to control the details of the conversion to the disc format (such
as setting the Q factor for a JPEG, for example), you embed extra control
characters in the filename. For example:
@ -283,23 +279,13 @@ void error_exit( const char *format,
There are other functions for handling errors: see the man page for
\verb+im_error()+.
If the file name given to \verb+im_open()+ ends with \verb+".v"+, VIPS
looks in the same directory as the image for a file with the same name
but with the extension \verb+".desc"+. If present, this file is read in
and a pointer to the data put in the \verb+Hist+ field of the descriptor. See
the notes on \verb+im_updatehist()+ in \pref{sec:examples}.
Descriptors are closed with \verb+im_close()+. It has type:
\begin{verbatim}
int im_close( IMAGE *im )
\end{verbatim}
\verb+im_close()+ returns 0 on success and non-zero on error.
If the descriptor represents a disc file which
has been written to and whose name ends in \verb+".v"+, VIPS writes the
\verb+Hist+ field of the image descriptor to a file in the same directory
whose name ends in \verb+".desc"+.
\verb+im_close()+ returns 0 on success and non-zero on error.
\subsection{Examples}
\label{sec:examples}
@ -394,10 +380,10 @@ main( int argc, char **argv )
\label{sec:meta}
VIPS lets you attach arbitrary metadata to an IMAGE. For example, ICC
profiles, EXIF tags, whatever you like. VIPS will efficiently propogate
metadata as images are processed (usually just by copying pointers) and will
automatically save and load metadata from VIPS files (see
\pref{sec:header}).
profiles, EXIF tags, image history, whatever you like. VIPS will efficiently
propagate metadata as images are processed (usually just by copying
pointers) and will automatically save and load metadata from VIPS files
(see \pref{sec:header}).
A piece of metadata is a value and an identifying name. A set of
convenience functions let you set and get int, double, string and blob. For
@ -432,9 +418,8 @@ if( im_meta_get_int( im, "poop", &i ) )
And get the value 42 back.
You can use \verb+im_meta_set()+ and \verb+im_meta_get()+ to attach arbitrary
\verb+GValue+ to images.
See the man page for \verb+im_meta_set()+ for full
details.
\verb+GValue+ to images. See the man page for \verb+im_meta_set()+ for
full details.
You can test for a field being present with \verb+im_meta_get_type()+ (you'll
get \verb+G_TYPE_INT+ back for \verb+"poop"+, for example, or 0 if it is not
@ -476,7 +461,7 @@ const char *
VIPS lets you attach callbacks to image descriptors. These are functions
you provide which VIPS will call when certain events occur. See
\pref{sec:callback} for a full list.
\pref{sec:callback} for more detail.
Eval callbacks are called repeatedly during evaluation and can be used by
user-interface programs to give feedback about the progress of evaluation.
@ -649,7 +634,7 @@ for more help.
All VIPS operations return 0 on success and non-zero on error, setting
\verb+im_error()+. As a consequence, when a VIPS function fails, you do not
need to generate an error message --- you can simply propogate the error back
need to generate an error message --- you can simply propagate the error back
up to your caller. If however you detect some error yourself (for example,
the bad parameter in the example above), you must call \verb+im_error()+
to let your caller know what the problem was.
@ -657,7 +642,7 @@ to let your caller know what the problem was.
VIPS provides two more functions for error message handling: \verb+im_warn()+
and \verb+im_diag()+. These are intended to be used for less serious
messages, as their names suggest. Currently, they simply format and print
their arguments to \verb+stderr+, optionally supressed by the setting of an
their arguments to \verb+stderr+, optionally suppressed by the setting of an
environment variable. Future releases of VIPS may allow more sophisticated
trapping of these functions to allow their text to be easily presented to
the user by VIPS applications. See the manual pages.
@ -700,8 +685,9 @@ images larger than the amount of RAM you have on your machine.
As an added bonus, if you have more than one CPU in your computer, the work
will be automatically spread across the processors for you. You can control
this parallelisation with the \verb+IM_CONCURRENCY+ environment variable and
with \verb+im_concurrency_set()+. See the man page for \verb+im_generate()+.
this parallelization with the \verb+IM_CONCURRENCY+ environment variable,
\verb+im_concurrency_set()+, and with the \verb+--vips-concurrency+
command-line switch. See the man page for \verb+im_generate()+.
\subsubsection{How it works}
@ -796,7 +782,8 @@ and throw it all away, keeping only the average value. The subsequent call to
When designing a program, it is sensible to pay attention to these
issues. It might be faster, in some cases, to output to a file before
calling \verb+im_avg()+, find the average of the disc file, and then run
\verb+im_moreconst()+ from that.
\verb+im_moreconst()+ from that. There's also \verb+im_cache()+ which can keep
recent parts of a very large image.
\subsubsection{Blocking computation}
\label{sec:block}
@ -814,7 +801,7 @@ from being followed.
\label{sec:limit}
Not all VIPS operations are partial-aware. These non-partial operations
use a pre-VIPS7.0 I/O scheme in which the whole of the input image has to
use a pre-VIPS 7.0 I/O scheme in which the whole of the input image has to
be present at the same time. In some cases, this is because partial I/O
simply makes no sense --- for example, a Fourier Transform can produce no
output until it has seen all of the input. \verb+im_fwfft()+ is therefore

134
doc/src/object.tex Normal file
View File

@ -0,0 +1,134 @@
\section{The VIPS base class: \texttt{VipsObject}}
\label{sec:object}
VIPS is in the process of moving to an object system based on \verb+GObject+.
You can read about the \verb+GObjec+ library at the GTK+ website:
\begin{verbatim}
http://www.gtk.org
\end{verbatim}
We've implemented two new subsystems (\verb+VipsFormat+ and
\verb+VipsInterpolate+) on top of \verb+VipsObject+ but not yet moved the core
VIPS types over. As a result, \verb+VipsObject+ is still developing and is
likely to change in the next release.
This section quickly summarises enough of the \verb+VipsObject+ system to let
you use the two derived APIs but that's all. Full documentation will come when
this system stabilises.
\subsection{Properties}
Like the rest of VIPS, \verb+VipsObject+ is a functional type. You can set
properties during object construction, but not after that point. You may read
properties at any time after construction, but not before.
To enforce these rules, VIPS extends the standard \verb+GObject+ property
system and adds a new phase to object creation. An object has the following
stages in its life:
\subsubsection{Lookup}
\verb+vips_type_find()+ is a convenience function that looks up a type by its
nickname relative to a base class. For example:
\begin{verbatim}
GType type =
vips_type_find( "VipsInterpolate", "bilinear" );
\end{verbatim}
\noindent
finds a subclass of \verb+VipsInterpolate+ nicknamed `bilinear'. You can look
up types by their full name of course, but these can be rather unwieldy
(\verb+VipsInterpolateBilinear+ in this case, for example).
\subsubsection{Create}
Build an instance with \verb+g_object_new()+. For example:
\begin{verbatim}
VipsObject *object =
g_object_new( type,
"sharpness", 12.0,
NULL );
\end{verbatim}
You can set any of the object's properties in the constructor. You can
continue to set, but not read, any other properties, for example:
\begin{verbatim}
g_object_set( object,
"sharpness", 12.0,
NULL );
\end{verbatim}
You can loop over an object's required and optional parameters with
\verb+vips_argument_map()+.
\subsubsection{Build}
Once all of the required any any of the optional object parameters have been
set, call \verb+vips_object_build()+:
\begin{verbatim}
int vips_object_build( VipsObject *object );
\end{verbatim}
This function checks that all the parameters have been set correctly and
starts the object working. It returns non-zero on error, setting
\verb+im_error_string()+.
\subsubsection{Use}
The object is now fully working. You can read results from it, or pass it on
other objects. When you're finished with it, drop your reference to end its
life.
\begin{verbatim}
g_object_unref( object );
\end{verbatim}
\subsection{Convenience functions}
Two functions simplify building and printing objects.
\verb+vips_object_new_from_string()+ makes a new object which is a subclass of
a named base class.
\begin{verbatim}
VipsObject *
vips_object_new_from_string(
const char *basename, const char *p );
\end{verbatim}
This is the function used by \verb+IM_INPUT_INTERPOLATE()+, for example, to
parse command-line arguments. The syntax is:
\begin{verbatim}
nickname [ ( required-arg1,
...
required-argn,
optional-arg-name = value,
...
optional-argm-name = value ) ]
\end{verbatim}
So values for all the required arguments, in the correct order, then name =
value for all the optional arguments you want to set. Parameters may be
enclosed in round or curly braces.
\verb+vips_object_to_string()+ is the exact opposite: it generates the
construct string for any constructed
\verb+VipsObject+.
\verb+vips_object_new()+ wraps up the business of creating and checking an
object. It makes the object, uses the supplied function to attach any
arguments, then builds the object and returns NULL on failure or the new
object on success.
A switch to the \verb+vips+ command-line program is handy for listing subtypes
of \verb+VipsObject+. Try:
\begin{verbatim}
$ vips --list classes
\end{verbatim}

13
doc/src/operintro.tex
View File

@ -37,8 +37,8 @@ Provided you use PIO and as long as the underlying OS supports large files
(that is, files larger than 2GB), VIPS operations can work on files larger
than can be addressed with 32 bits on a plain 32-bit machine. VIPS operations
only see 32 bit addresses; the VIPS I/O system transparently maps these to
64 bit operations for I/O. Large file support is included on most unixes after
about 1998.
64 bit operations for I/O. Large file support is included on most machines
after about 1998.
\item[Abstraction]
VIPS operations see only arrays of numbers in native format. Details of
@ -98,12 +98,3 @@ and \verb+im_wrapmany()+ operations. These take a simple buffer-processing
operation supplied by you and wrap it up as a full-blown PIO operation.
See~\pref{sec:wrapone}.
\subsection{What's new in this version}
The VIPS API is mostly unaltered since 7.3, so there are not many major
changes. I've just reworked the text, reformatted, fixed a few typos,
and changed the dates.
VIPS has acquired some crud over the years. We are planning to clean all
this stuff up at some stage (and break backwards-compatibility). Maybe for
VIPS 8 :-(

59
doc/src/packages.tex
View File

@ -21,7 +21,7 @@ in the manual pages.
\begin{fig2}
\begin{verbatim}
john% vips --list arithmetic
$ vips --list arithmetic
im_abs - absolute value
im_acostra - acos of image (result in degrees)
im_add - add two images
@ -63,7 +63,7 @@ im_powtra - pel^x ofbuildimage
im_powtra_vec - pel^[x,y,z] of image
im_remainder - remainder after integer division
im_remainderconst - remainder after integer division by a constant
im_remainderconst_vec - remainder after int division by vector of constants
im_remainderconst_vec - remainder after integer division by a vector of constants
im_rint - round to nearest integal value
im_sign - unit vector in direction of value
im_sintra - sin of image (angles in degrees)
@ -92,7 +92,7 @@ condition is true (or false) for a whole image.
\begin{fig2}
\begin{verbatim}
john% vips --list relational
$ vips --list relational
im_blend - use cond image to blend between images in1 and in2
im_equal - two images equal in value
im_equal_vec - image equals doublevec
@ -129,7 +129,7 @@ the relational and morphological functions. You can use
\begin{fig2}
\begin{verbatim}
john% vips --list boolean
$ vips --list boolean
im_andimage - bitwise and of two images
im_andimageconst - bitwise and of an image with a constant
im_andimage_vec - bitwise and of an image with a vector constant
@ -228,7 +228,7 @@ or \verb+disp+ colour space.
\begin{fig2}
\begin{verbatim}
example% vips --list colour
$ vips --list colour
im_LCh2Lab - convert LCh to Lab
im_LCh2UCS - convert LCh to UCS
im_Lab2LCh - convert Lab to LCh
@ -262,6 +262,7 @@ im_dE_fromXYZ - calculate delta-E for two XYZ images
im_dE_fromdisp - calculate delta-E for two displayable images
im_disp2Lab - convert displayable to Lab
im_disp2XYZ - convert displayable to XYZ
im_float2rad - convert float to Radiance packed
im_icc_ac2rc - convert LAB from AC to RC using an ICC profile
im_icc_export - convert a float LAB to an 8-bit device image with an ICC profile
im_icc_export_depth - convert a float LAB to device space with an ICC profile
@ -270,6 +271,7 @@ im_icc_import_embedded - convert a device image to float LAB using the embedded
im_icc_present - test for presence of ICC library
im_icc_transform - convert between two device images with a pair of ICC profiles
im_lab_morph - morph colourspace of a LAB image
im_rad2float - convert Radiance packed to float
im_sRGB2XYZ - convert sRGB to XYZ
\end{verbatim}
\caption{Colour functions}
@ -293,7 +295,7 @@ join of many images at the same time. See the manual pages.
\begin{fig2}
\begin{verbatim}
example% vips --list conversion
$ vips --list conversion
im_bandjoin - bandwise join of two images
im_bernd - extract from pyramid as jpeg
im_black - generate black image
@ -421,7 +423,7 @@ sections.
\begin{fig2}
\begin{verbatim}
example% vips --list matrix
$ vips --list matrix
im_matcat - append matrix in2 to the end of matrix in1
im_matinv - invert matrix
im_matmul - multiply matrix in1 by matrix in2
@ -467,7 +469,7 @@ expect.
\begin{fig2}
\begin{verbatim}
example% vips --list convolution
$ vips --list convolution
im_addgnoise - add gaussian noise with mean 0 and std. dev. sigma
im_compass - convolve with 8-way rotating integer mask
im_contrast_surface - find high-contrast points in an image
@ -488,6 +490,7 @@ im_fastcor - fast correlate in2 within in1
im_fastcor_raw - fast correlate in2 within in1, no border
im_gauss_dmask - generate gaussian DOUBLEMASK
im_gauss_imask - generate gaussian INTMASK
im_gauss_imask_sep - generate separable gaussian INTMASK
im_gaussnoise - generate image of gaussian noise with specified statistics
im_grad_x - horizontal difference image
im_grad_y - vertical difference image
@ -532,7 +535,7 @@ not.
\begin{fig2}
\begin{verbatim}
example% vips --list inplace
$ vips --list inplace
im_circle - plot circle on image
im_flood_blob_copy - flood while pixel == start pixel
im_insertplace - draw image sub inside image main at position (x,y)
@ -571,7 +574,7 @@ for an image.
\begin{fig2}
\begin{verbatim}
example% vips --list freq_filt
$ vips --list freq_filt
im_create_fmask - create frequency domain filter mask
im_disp_ps - make displayable power spectrum
im_flt_image_freq - frequency domain filter image
@ -611,7 +614,7 @@ functions are useful combinations of these basic operations.
\begin{fig2}
\begin{verbatim}
example% vips --list histograms_lut
$ vips --list histograms_lut
im_gammacorrect - gamma-correct image
im_heq - histogram-equalise image
im_hist - find and graph histogram of image
@ -692,7 +695,7 @@ union operations.
\begin{fig2}
\begin{verbatim}
example% vips --list morphology
$ vips --list morphology
im_cntlines - count horizontal or vertical lines
im_dilate - dilate image with mask, adding a black border
im_dilate_raw - dilate image with mask
@ -744,8 +747,7 @@ images.
\begin{fig2}
\begin{verbatim}
example% vips --list mosaicing
im_affine - affine transform
$ vips --list mosaicing
im_align_bands - align the bands of an image
im_correl - search area around sec for match for area around ref
im__find_lroverlap - search for left-right overlap of ref and sec
@ -760,8 +762,6 @@ im_match_linear - resample ref so that tie-points match
im_match_linear_search - search sec, then resample so that tie-points match
im_maxpos_subpel - subpixel position of maximum of (phase correlation) image
im_remosaic - automatically rebuild mosaic with new files
im_similarity_area - output area xywh of similarity transformation
im_similarity - similarity transformation
im_tbmerge - top-bottom merge of in1 and in2
im_tbmerge1 - first-order top-bottom merge of in1 and in2
im_tbmosaic - top-bottom mosaic of in1 and in2
@ -780,7 +780,7 @@ They are useful for removing noise from images.
\begin{fig2}
\begin{verbatim}
example% vips --list cimg
$ vips --list cimg
im_greyc - noise-removing filter
im_greyc_mask - noise-removing filter, with a mask
\end{verbatim}
@ -799,7 +799,7 @@ The \verb+im_benchmark*()+ operations are for testing the VIPS SMP system.
\begin{fig2}
\begin{verbatim}
example% vips --list other
$ vips --list other
im_benchmark - do something complicated for testing
im_benchmark2 - do something complicated for testing
im_benchmarkn - do something complicated for testing
@ -823,7 +823,7 @@ These functions are related to the image IO system.
\begin{fig2}
\begin{verbatim}
example% vips --list iofuncs
$ vips --list iofuncs
im_binfile - open a headerless binary file
im_cache - cache results of an operation
im_guess_prefix - guess install area
@ -848,7 +848,7 @@ These functions convert to and from various image formats. See
\begin{fig2}
\begin{verbatim}
example% vips --list format
$ vips --list format
im_csv2vips - read a file in csv format
im_jpeg2vips - convert from jpeg
im_magick2vips - load file with libMagick
@ -867,3 +867,22 @@ im_vips2tiff - convert VIPS image to TIFF file
\caption{Format functions}
\label{fg:format}
\end{fig2}
\subsection{Resample functions}
See \fref{fg:resample}.
These functions resample images with various interpolators.
\begin{fig2}
\begin{verbatim}
$ vips --list resample
im_affine - affine transform
im_affinei - affine transform
im_affinei_all - affine transform of whole image
im_similarity_area - output area xywh of similarity transformation
im_similarity - similarity transformation
\end{verbatim}
\caption{Resample functions}
\label{fg:resample}
\end{fig2}

16
doc/src/refintro.tex
View File

@ -43,10 +43,10 @@ user-interfaces, or you can run it from the UNIX command line with the
\vips{} program. For example:
\begin{verbatim}
john% vips im_vips2tiff cam.v t1.tif none
john% vips im_tiff2vips t1.tif t2.v.v 0
john% vips im_equal cam.v t2.v t3.v
john% vips im_min t3.v
$ vips im_vips2tiff cam.v t1.tif none
$ vips im_tiff2vips t1.tif t2.v.v 0
$ vips im_equal cam.v t2.v t3.v
$ vips im_min t3.v
255
\end{verbatim}
@ -54,10 +54,10 @@ VIPS may have been set up at your site with a set of links which call the
vips program for you. You may also be able to type:
\begin{verbatim}
john% im_vips2tiff cam.v t1.tif none
john% im_tiff2vips t1.tif t2.v.v 0
john% im_equal cam.v t2.v t3.v
john% im_min t3.v
$ im_vips2tiff cam.v t1.tif none
$ im_tiff2vips t1.tif t2.v.v 0
$ im_equal cam.v t2.v t3.v
$ im_min t3.v
\end{verbatim}
There are a few VIPS programs which you cannot run with \vips{}, either

2
doc/src/vdisplay.tex
View File

@ -3,7 +3,7 @@
The \verb+VDisplay+ class is an abstraction over the VIPS \verb+im_col_display+
type which gives convenient and safe representation of VIPS display profiles.
VIPS display profiles are now obsolete. You're better off using the
VIPS display profiles are now mostly obsolete. You're better off using the
ICC colour management \verb+VImage+ member functions \verb+ICC_export()+ and
\verb+ICC_import()+.

3
doc/src/vipsmanual.tex
View File

@ -27,7 +27,7 @@
\begin{center}
\huge
VIPS Manual\\
\large Version 7.14\\
\large Version 7.18\\
\vspace{0.5in}
\large
John Cupitt,
@ -72,6 +72,7 @@ This manual formatted \today
\input{applintro}
\input{iosys}
\input{func}
\input{object}
\input{format}
\input{interpolate}

11
doc/src/vmask.tex
View File

@ -2,10 +2,10 @@
The \verb+VMask+ class is an abstraction over the VIPS \verb+DOUBLEMASK+ and
\verb+INTMASK+ types which gives convenient and safe representation of
matricies.
matrices.
\verb+VMask+ has two sub-classes, \verb+VIMask+ and \verb+VDMask+. These
represent matricies of integers and doubles respectively.
represent matrices of integers and doubles respectively.
\subsection{Constructors}
@ -109,6 +109,13 @@ for( int x = 0; x < fred.xsize(); x++ )
\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}