From 1160f6a4b768a3bc9f3f5532de9c40e98dfb2c51 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Fri, 27 Mar 2009 17:23:11 +0000 Subject: [PATCH] stuff --- ChangeLog | 1 + TODO | 12 ++-- doc/src/applintro.tex | 4 +- doc/src/format.tex | 20 ++---- doc/src/func.tex | 81 ++++++++++++++---------- doc/src/interpolate.tex | 76 +++++++++++++++-------- doc/src/iosys.tex | 77 ++++++++++------------- doc/src/object.tex | 134 ++++++++++++++++++++++++++++++++++++++++ doc/src/operintro.tex | 13 +--- doc/src/packages.tex | 59 ++++++++++++------ doc/src/refintro.tex | 16 ++--- doc/src/vdisplay.tex | 2 +- doc/src/vipsmanual.tex | 3 +- doc/src/vmask.tex | 11 +++- 14 files changed, 343 insertions(+), 166 deletions(-) create mode 100644 doc/src/object.tex diff --git a/ChangeLog b/ChangeLog index ac170b22..f8ac47f4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -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 diff --git a/TODO b/TODO index d24ad505..2313f777 100644 --- a/TODO +++ b/TODO @@ -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 ================ diff --git a/doc/src/applintro.tex b/doc/src/applintro.tex index 690300fe..f1bb3de4 100644 --- a/doc/src/applintro.tex +++ b/doc/src/applintro.tex @@ -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 diff --git a/doc/src/format.tex b/doc/src/format.tex index 63c45d10..b175c8d8 100644 --- a/doc/src/format.tex +++ b/doc/src/format.tex @@ -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 diff --git a/doc/src/func.tex b/doc/src/func.tex index 1448bd04..e83ac2d9 100644 --- a/doc/src/func.tex +++ b/doc/src/func.tex @@ -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} diff --git a/doc/src/interpolate.tex b/doc/src/interpolate.tex index 7e4a1846..dfefc7a2 100644 --- a/doc/src/interpolate.tex +++ b/doc/src/interpolate.tex @@ -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}. diff --git a/doc/src/iosys.tex b/doc/src/iosys.tex index 25ff42d3..20e3195a 100644 --- a/doc/src/iosys.tex +++ b/doc/src/iosys.tex @@ -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 diff --git a/doc/src/object.tex b/doc/src/object.tex new file mode 100644 index 00000000..6f8bbad8 --- /dev/null +++ b/doc/src/object.tex @@ -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} + diff --git a/doc/src/operintro.tex b/doc/src/operintro.tex index 20ae3db3..5d9ee25d 100644 --- a/doc/src/operintro.tex +++ b/doc/src/operintro.tex @@ -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 :-( diff --git a/doc/src/packages.tex b/doc/src/packages.tex index 89921aa1..542a6a8b 100644 --- a/doc/src/packages.tex +++ b/doc/src/packages.tex @@ -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} diff --git a/doc/src/refintro.tex b/doc/src/refintro.tex index 3d750f9c..2632507e 100644 --- a/doc/src/refintro.tex +++ b/doc/src/refintro.tex @@ -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 diff --git a/doc/src/vdisplay.tex b/doc/src/vdisplay.tex index 7c5080dc..f244be71 100644 --- a/doc/src/vdisplay.tex +++ b/doc/src/vdisplay.tex @@ -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()+. diff --git a/doc/src/vipsmanual.tex b/doc/src/vipsmanual.tex index 744394bd..f00af00c 100644 --- a/doc/src/vipsmanual.tex +++ b/doc/src/vipsmanual.tex @@ -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} diff --git a/doc/src/vmask.tex b/doc/src/vmask.tex index 5dfc1c7b..4f0a8871 100644 --- a/doc/src/vmask.tex +++ b/doc/src/vmask.tex @@ -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}