Top | ![]() |
![]() |
![]() |
![]() |
gint | bands | Read / Write |
VipsCoding | coding | Read / Write |
VipsDemandStyle | demand | Read / Write |
gchar * | filename | Read / Write |
gpointer | foreign-buffer | Read / Write |
VipsBandFormat | format | Read / Write |
gint | height | Read / Write |
VipsInterpretation | interpretation | Read / Write |
gboolean | kill | Read / Write |
gchar * | mode | Read / Write |
guint64 | sizeof-header | Read / Write |
gint | width | Read / Write |
gint | xoffset | Read / Write |
gdouble | xres | Read / Write |
gint | yoffset | Read / Write |
gdouble | yres | Read / Write |
enum | VipsDemandStyle |
enum | VipsImageType |
enum | VipsInterpretation |
enum | VipsBandFormat |
enum | VipsCoding |
enum | VipsAccess |
VipsProgress |
The image class and associated types and macros.
vips_image_wio_input() and friends indicate the image IO style you intend to use, transforming the underlying VipsImage structure if necessary.
#define VIPS_MAGIC_INTEL (0xb6a6f208U)
The first four bytes of a VIPS file in Intel byte ordering.
#define VIPS_MAGIC_SPARC (0x08f2a6b6U)
The first four bytes of a VIPS file in SPARC byte ordering.
#define VIPS_IMAGE_ADDR( I, X, Y )
This macro returns a pointer to a pixel in an image, cast to a VipsPel *. It only works for images which are fully available in memory, so memory buffers and small mapped images only.
If VIPS_DEBUG is defined, you get a version that checks bounds for you.
See also: VIPS_REGION_ADDR()
.
#define VIPS_MATRIX( I, X, Y )
This macro returns a pointer to a pixel in an image, cast to a double*. The image must have a single band, be VIPS_FORMAT_DOUBLE and be fully available in memory, so memory buffers and small mapped images only.
If VIPS_DEBUG is defined, you get a version that checks bounds and image type for you.
See also: VIPS_IMAGE_ADDR()
.
void
vips_image_invalidate_all (VipsImage *image
);
Invalidate all pixel caches on an image
and any downstream images, that
is, images which depend on this image.
The "invalidate" callback is triggered for all invalidated images.
void
vips_image_minimise_all (VipsImage *image
);
Minimise memory use on this image and any upstream images, that is, images which this image depends upon.
The "minimise" callback is triggered for all minimised images.
void vips_image_set_progress (VipsImage *image
,gboolean progress
);
vips signals evaluation progress via the "preeval", "eval" and "posteval"
signals. Progress is signalled on the most-downstream image for which
vips_image_set_progress()
was called.
VipsImage *
vips_image_new (void
);
vips_image_new() creates a "glue" descriptor you can use to join two image processing operations together.
It is the equivalent of vips_image_new_mode("xxx", "p").
VipsImage * vips_image_new_mode (const char *filename
,const char *mode
);
vips_image_new_mode() examines the mode string and creates an appropriate VipsImage.
"t" creates a temporary memory buffer image.
"p"
creates a "glue" descriptor you can use to join operations, see also
vips_image_new()
.
"r"
opens the named file for reading. If the file is not in the native
VIPS format for your machine, vips_image_new_mode()
automatically converts the file for you.
Some formats (eg. tiled tiff) are read directly.
Some formats (eg. strip tiff) do not support random access and can't
be processed directly. Small images are decompressed to memory and
loaded from there, large images are decompressed to a disc file and
processed from that.
If the operations you intend to perform are sequential, that is, they
operate in a strict top-to-bottom manner, you can use sequential mode
instead, see "rs" below,
or you can use the lower-level
API and control the loading process yourself. See
VipsForeign.
See vips_image_new_temp_file()
for an explanation of how VIPS selects a
location for the temporary file.
The disc threshold can be set with the "--vips-disc-threshold"
command-line argument, or the IM_DISC_THRESHOLD environment variable.
The value is a simple integer, but can take a unit postfix of "k",
"m" or "g" to indicate kilobytes, megabytes or gigabytes.
For example:
vips --vips-disc-threshold 500m copy fred.tif fred.v
will copy via disc if "fred.tif" is more than 500 Mbytes uncompressed. The default threshold is 100 MB. Note that "r" mode works in at least two stages. It should return quickly and let you check header fields. It will only actually read in pixels when you first access them.
"rs" opens the named file for reading sequentially. It reads the source image top-to-bottom and serves up pixels to the pipeline as required. Provided the operations that connect to the image all demand pixels only top-to-bottom as well, everything is fine and you avoid the separate decompress stage.
"w" opens the named file for writing. It looks at the file name suffix to determine the type to write -- for example:
vips_image_new_mode( "fred.tif", "w" )
will write in TIFF format.
"rw" opens the named file for reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications.
VipsImage *
vips_image_new_buffer (void
);
vips_image_new_buffer() creates a new VipsImage which when written to will
create a memory buffer. It is a convenience function for
vips_image_new_mode(vips_image_temp_name()
, "t").
See also: vips_image_new()
.
VipsImage *
vips_image_new_from_file (const char *filename
);
vips_image_new_from_file() opens filename
for reading in mode "r". See
vips_image_new_mode()
for details.
See also: vips_image_new_mode()
.
VipsImage * vips_image_new_from_file_raw (const char *filename
,int xsize
,int ysize
,int bands
,guint64 offset
);
This function maps the named file and returns a VipsImage you can use to read it.
It returns an 8-bit image with bands
bands. If the image is not 8-bit, use
im_copy_set()
to transform the descriptor after loading it.
See also: im_copy_set()
, im_raw2vips()
, vips_image_new_from_file()
.
VipsImage * vips_image_new_from_memory (void *buffer
,int xsize
,int ysize
,int bands
,VipsBandFormat bandfmt
);
This function wraps an IMAGE around a memory buffer. VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example “close”.
See also: im_binfile()
, im_raw2vips()
, vips_image_new()
.
VipsImage * vips_image_new_matrix (int width
,int height
);
This convenience function makes an image which is a matrix: a one-band VIPS_FORMAT_DOUBLE image held in memory.
Use VIPS_IMAGE_ADDR()
, or VIPS_MATRIX()
to address pixels in the image.
Use vips_image_set_double()
to set "scale" and "offset", if required.
See also: vips_image_new_matrixv()
VipsImage * vips_image_new_matrixv (int width
,int height
,...
);
As vips_image_new_matrix()
, but initialise the matrix from the argument
list. After height
should be width
* height
double constants which are
used to set the matrix elements.
See also: vips_image_new_matrix()
void vips_image_set_delete_on_close (VipsImage *image
,gboolean delete_on_close
);
Sets the delete_on_close flag for the image. If this flag is set, when
image
is finalized, the filename held in image->filename
at the time of
this call is unlinked.
This function is clearly extremely dangerous, use with great caution.
See also: vips__temp_name()
, vips_image_new_temp_file()
.
VipsImage *
vips_image_new_temp_file (const char *format
);
Make a "w" disc VipsImage which will be automatically unlinked when it is
destroyed. format
is something like "s
.v" for a vips file.
The file is created in the temporary directory, see vips__temp_name()
.
See also: vips__temp_name()
.
int vips_image_write (VipsImage *image
,VipsImage *out
);
Write image
to out
. Use vips_image_new_mode()
and friends to create the
VipsImage you want to write to.
See also: vips_image_new_mode()
, vips_copy()
, vips_image_write_to_file()
.
int vips_image_write_to_file (VipsImage *image
,const char *filename
);
A convenience function to write image
to a file.
gboolean
vips_image_isMSBfirst (VipsImage *image
);
Return TRUE
if image
is in most-significant-
byte first form. This is the byte order used on the SPARC
architecture and others.
gboolean
vips_image_isfile (VipsImage *image
);
Return TRUE
if image
represents a file on disc in some way.
gboolean
vips_image_ispartial (VipsImage *image
);
Return TRUE
if im
represents a partial image (a delayed calculation).
int
vips_image_wio_input (VipsImage *image
);
Check that an image is readable via the VIPS_IMAGE_ADDR()
macro, that is,
that the entire image is in memory and all pixels can be read with
VIPS_IMAGE_ADDR()
.
If it
isn't, try to transform it so that VIPS_IMAGE_ADDR()
can work.
See also: vips_image_wio_output()
, vips_image_pio_input()
,
vips_image_inplace()
, VIPS_IMAGE_ADDR()
.
int
vips_image_pio_input (VipsImage *image
);
Check that an image is readable with vips_region_prepare()
and friends.
If it isn't, try to transform the image so that vips_region_prepare()
can
work.
See also: vips_image_pio_output()
, vips_region_prepare()
.
int
vips_image_inplace (VipsImage *image
);
Gets image
ready for an in-place operation, such as im_insertplace()
.
After calling this function you can both read and write the image with
VIPS_IMAGE_ADDR()
.
See also: im_insertplace()
, vips_image_wio_input()
.
int
vips_image_write_prepare (VipsImage *image
);
Call this after setting header fields (width, height, and so on) to allocate resources ready for writing.
Normally this function is called for you by vips_image_generate()
or
vips_image_write_line()
. You will need to call it yourself if you plan to
write directly to the ->data member of a "t" image.
int vips_image_write_line (VipsImage *image
,int ypos
,VipsPel *linebuffer
);
Write a line of pixels to an image. This function must be called repeatedly
with ypos
increasing from 0 to YSize
-
linebuffer
must be VIPS_IMAGE_SIZEOF_LINE()
bytes long.
See also: vips_image_generate()
.
gboolean
vips_band_format_isint (VipsBandFormat format
);
Return TRUE
if format
is one of the integer types.
gboolean
vips_band_format_isuint (VipsBandFormat format
);
Return TRUE
if format
is one of the unsigned integer types.
gboolean
vips_band_format_is8bit (VipsBandFormat format
);
Return TRUE
if format
is uchar or schar.
gboolean
vips_band_format_isfloat (VipsBandFormat format
);
Return TRUE
if format
is one of the float types.
gboolean
vips_band_format_iscomplex (VipsBandFormat format
);
Return TRUE
if fmt
is one of the complex types.
int vips_system (const char *cmd_format
,...
);
Optional arguments:
in
: input image
out
: output image
in_format
: write input file like this
out_format
: write output filename like this
log
: stdout of command is returned here
vips_system() runs a command, optionally passing an image in and
optionally getting an image
back. The command's stdout is returned in log
.
First, if in
is set, it is written to a file. The filename is formed by
substituting something like "vips-49857-1" for the first %s
in in_format
,
then
prepending "/tmp". If the environment variable TMPDIR is defined, it
can be used to set a different temporary directory.
On Windows, if the environment variable TMPDIR is not defined, VIPS calls
GetTempPath()
to get the user's preferred temporary area. If that fails, it
defaults to C:\temp.
If in_format
is
something like "%s
.png", the file will be written in PNG format. By
default, in_format
is "%s
.tif".
If out_format
is set, an output filename is formed in the same way.
The
command string to run is made by substituting the first %s
in cmd_format
for the name of the input file, if in
is set, and the second %s
for the
output filename, if set.
The command is executed with popen()
and the output captured in log
.
After the command finishes, if out_format
is set, the output image is
opened and returned in out
.
Closing the output image will automatically delete the output file.
Finally the input images are deleted.
For example, this call will run the ImageMagick convert program on an image, using JPEG files to pass images into and out of the convert command.
VipsImage *in; VipsImage *out; char *log; if (vips_system ("convert %s -swirl 45 %s", "in", in, "out", &out, "in_format", "%s.jpg", "out_format", "%s.jpg", "log", &log, NULL)) error ...
See vips_image_pipelinev()
. Operations can hint to the VIPS image IO system about
the kind of demand geometry they prefer.
These demand styles are given below in order of increasing
restrictiveness. When demanding output from a pipeline,
vips_image_generate()
will use the most restrictive of the styles requested by the operations
in the pipeline.
VIPS_DEMAND_STYLE_THINSTRIP --- This operation would like to output strips the width of the image and a few pels high. This is option suitable for point-to-point operations, such as those in the arithmetic package.
This option is only efficient for cases where each output pel depends upon the pel in the corresponding position in the input image.
VIPS_DEMAND_STYLE_FATSTRIP --- This operation would like to output strips
the width of the image and as high as possible. This option is suitable
for area operations which do not violently transform coordinates, such
as im_conv()
.
VIPS_DEMAND_STYLE_SMALLTILE --- This is the most general demand format. Output is demanded in small (around 100x100 pel) sections. This style works reasonably efficiently, even for bizzare operations like 45 degree rotate.
VIPS_DEMAND_STYLE_ANY --- This image is not being demand-read from a disc
file (even indirectly) so any demand style is OK. It's used for things like
im_black()
where the pixels are calculated.
See also: vips_image_pipelinev()
.
How the values in an image should be interpreted. For example, a three-band float image of type VIPS_INTERPRETATION_LAB should have its pixels interpreted as coordinates in CIE Lab space.
These values are set by operations as hints to user-interfaces built on top of VIPS to help them show images to the user in a meaningful way. Operations do not use these values to decide their action.
The gaps in the numbering are historical and must be maintained. Allocate new numbers from the end.
generic many-band image |
||
some kind of single-band image |
||
a 1D image, eg. histogram or lookup table |
||
the first three bands are CIE XYZ |
||
pixels are in CIE Lab space |
||
the first four bands are in CMYK space |
||
implies VIPS_CODING_LABQ |
||
generic RGB space |
||
a uniform colourspace based on CMC(1:1) |
||
pixels are in CIE LCh space |
||
CIE LAB coded as three signed 16-bit values |
||
pixels are sRGB |
||
pixels are CIE Yxy |
||
image is in fourier space |
||
generic 16-bit RGB |
||
generic 16-bit mono |
||
a matrix |
||
pixels are scRGB |
The format used for each band element.
Each corresponnds to a native C type for the current machine. For example, VIPS_FORMAT_USHORT is unsigned short.
How pixels are coded.
Normally, pixels are uncoded and can be manipulated as you would expect. However some file formats code pixels for compression, and sometimes it's useful to be able to manipulate images in the coded format.
The gaps in the numbering are historical and must be maintained. Allocate new numbers from the end.
The type of access an operation has to supply. See vips_tilecache()
and VipsForeign.
VIPS_ACCESS_RANDOM
means requests can come in any order.
VIPS_ACCESS_SEQUENTIAL
means requests will be top-to-bottom, but with some
amount of buffering behind the read point for small non-local accesses.
VIPS_ACCESS_SEQUENTIAL_UNBUFFERED
means requests will be strictly
top-to-bottom with no read-behind. This can save some memory.
typedef struct { int run; /* Time we have been running */ int eta; /* Estimated seconds of computation left */ gint64 tpels; /* Number of pels we expect to calculate */ gint64 npels; /* Number of pels calculated so far */ int percent; /* Percent complete */ GTimer *start; /* Start time */ } VipsProgress;
A structure available to eval callbacks giving information on evaluation progress. See “eval”.
Time we have been running |
||
Estimated seconds of computation left |
||
Number of pels we expect to calculate |
||
Number of pels calculated so far |
||
Percent complete |
||
GTimer * |
Start time |
“bands”
property“bands” gint
Number of bands in image.
Flags: Read / Write
Allowed values: [1,1000000000]
Default value: 1
“coding”
property“coding” VipsCoding
Pixel coding.
Flags: Read / Write
Default value: VIPS_CODING_NONE
“demand”
property“demand” VipsDemandStyle
Preferred demand style for this image.
Flags: Read / Write
Default value: VIPS_DEMAND_STYLE_SMALLTILE
“foreign-buffer”
property“foreign-buffer” gpointer
Pointer to foreign pixels.
Flags: Read / Write
“format”
property“format” VipsBandFormat
Pixel format in image.
Flags: Read / Write
Default value: VIPS_FORMAT_UCHAR
“height”
property“height” gint
Image height in pixels.
Flags: Read / Write
Allowed values: [1,1000000000]
Default value: 1
“interpretation”
property“interpretation” VipsInterpretation
Pixel interpretation.
Flags: Read / Write
Default value: VIPS_INTERPRETATION_MULTIBAND
“kill”
property“kill” gboolean
Block evaluation on this image.
Flags: Read / Write
Default value: FALSE
“sizeof-header”
property “sizeof-header” guint64
Offset in bytes from start of file.
Flags: Read / Write
Allowed values: <= 1000000
Default value: 64
“width”
property“width” gint
Image width in pixels.
Flags: Read / Write
Allowed values: [1,1000000000]
Default value: 1
“xoffset”
property“xoffset” gint
Horizontal offset of origin.
Flags: Read / Write
Allowed values: [-1000000,1000000]
Default value: 0
“xres”
property“xres” gdouble
Horizontal resolution in pixels/mm.
Flags: Read / Write
Allowed values: [-0,1e+06]
Default value: 0
“yoffset”
property“yoffset” gint
Vertical offset of origin.
Flags: Read / Write
Allowed values: [-1000000,1000000]
Default value: 0
“yres”
property“yres” gdouble
Vertical resolution in pixels/mm.
Flags: Read / Write
Allowed values: [-0,1e+06]
Default value: 0
“eval”
signalvoid user_function (VipsImage *vipsimage, gpointer arg1, gpointer user_data)
Flags: Run Last
“posteval”
signalvoid user_function (VipsImage *vipsimage, gpointer arg1, gpointer user_data)
Flags: Run Last
“preeval”
signalvoid user_function (VipsImage *vipsimage, gpointer arg1, gpointer user_data)
Flags: Run Last