Top |
Functions
int | vips_shrink () |
int | vips_shrinkh () |
int | vips_shrinkv () |
int | vips_reduce () |
int | vips_reduceh () |
int | vips_reducev () |
int | vips_thumbnail () |
int | vips_thumbnail_buffer () |
int | vips_thumbnail_image () |
int | vips_similarity () |
int | vips_affine () |
int | vips_resize () |
int | vips_mapim () |
int | vips_quadratic () |
Description
There are three types of operation in this section.
First, vips_affine()
applies an affine transform to an image. This is any
sort of 2D transform which preserves straight lines; so any combination of
stretch, sheer, rotate and translate. You supply an interpolator for it to
use to generate pixels, see vips_interpolate_new()
. It will not produce
good results for very large shrinks: you'll see aliasing.
vips_reduce() is like vips_affine()
, but it can only shrink images, it can't
enlarge, rotate, or skew. It's very fast and uses an adaptive kernel for
interpolation. Again, it will give poor results for large size reductions.
vips_shrink() is a fast block shrinker. It can quickly reduce images by large integer factors. It will give poor results for small size reductions: again, you'll see aliasing.
Next, vips_resize()
specialises in the common task of image reduce and
enlarge. It strings together combinations of vips_shrink()
, vips_reduce()
,
vips_affine()
and others to implement a general, high-quality image
resizer.
Finally, vips_mapim()
can apply arbitrary 2D image transforms to an image.
Functions
vips_shrink ()
int vips_shrink (VipsImage *in
,VipsImage **out
,double hshrink
,double vshrink
,...
);
Shrink in
by a pair of factors with a simple box filter. For non-integer
factors, vips_shrink()
will first shrink by the integer part with a box
filter, then use vips_reduce()
to shrink by the
remaining fractional part.
This is a very low-level operation: see vips_resize()
for a more
convenient way to resize images.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_resize()
, vips_reduce()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
hshrink |
horizontal shrink |
|
vshrink |
vertical shrink |
|
... |
|
vips_shrinkh ()
int vips_shrinkh (VipsImage *in
,VipsImage **out
,int hshrink
,...
);
Shrink in
horizontally by an integer factor. Each pixel in the output is
the average of the corresponding line of hshrink
pixels in the input.
This is a very low-level operation: see vips_resize()
for a more
convenient way to resize images.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_shrinkv()
, vips_shrink()
, vips_resize()
, vips_affine()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
hshrink |
horizontal shrink |
|
... |
|
vips_shrinkv ()
int vips_shrinkv (VipsImage *in
,VipsImage **out
,int vshrink
,...
);
Shrink in
vertically by an integer factor. Each pixel in the output is
the average of the corresponding column of vshrink
pixels in the input.
This is a very low-level operation: see vips_resize()
for a more
convenient way to resize images.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_shrinkh()
, vips_shrink()
, vips_resize()
, vips_affine()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
vshrink |
vertical shrink |
|
... |
|
vips_reduce ()
int vips_reduce (VipsImage *in
,VipsImage **out
,double hshrink
,double vshrink
,...
);
Optional arguments:
kernel
: VipsKernel to use to interpolate (default: lanczos3)centre
:gboolean
use centre rather than corner sampling convention
Reduce in
by a pair of factors with a pair of 1D kernels. This
will not work well for shrink factors greater than three.
Set centre
to use centre rather than corner sampling convention. Centre
convention can be useful to match the behaviour of other systems.
This is a very low-level operation: see vips_resize()
for a more
convenient way to resize images.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_resize()
, vips_affine()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
hshrink |
horizontal shrink |
|
vshrink |
vertical shrink |
|
... |
|
vips_reduceh ()
int vips_reduceh (VipsImage *in
,VipsImage **out
,double hshrink
,...
);
Optional arguments:
kernel
: VipsKernel to use to interpolate (default: lanczos3)centre
:gboolean
use centre rather than corner sampling convention
Reduce in
horizontally by a float factor. The pixels in out
are
interpolated with a 1D mask generated by kernel
.
Set centre
to use centre rather than corner sampling convention. Centre
convention can be useful to match the behaviour of other systems.
This is a very low-level operation: see vips_resize()
for a more
convenient way to resize images.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_shrink()
, vips_resize()
, vips_affine()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
hshrink |
horizontal reduce |
|
... |
|
vips_reducev ()
int vips_reducev (VipsImage *in
,VipsImage **out
,double vshrink
,...
);
Optional arguments:
kernel
: VipsKernel to use to interpolate (default: lanczos3)centre
:gboolean
use centre rather than corner sampling convention
Reduce in
vertically by a float factor. The pixels in out
are
interpolated with a 1D mask generated by kernel
.
Set centre
to use centre rather than corner sampling convention. Centre
convention can be useful to match the behaviour of other systems.
This is a very low-level operation: see vips_resize()
for a more
convenient way to resize images.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_shrink()
, vips_resize()
, vips_affine()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
vshrink |
vertical reduce |
|
... |
|
vips_thumbnail ()
int vips_thumbnail (const char *filename
,VipsImage **out
,int width
,...
);
Optional arguments:
height
:gint
, target height in pixelssize
: VipsSize, upsize, downsize, both or forceauto_rotate
:gboolean
, rotate upright using orientation tagcrop
: VipsInteresting, shrink and crop to fill targetlinear
:gboolean
, perform shrink in linear lightimport_profile
:gchararray
, fallback import ICC profileexport_profile
:gchararray
, export ICC profileintent
: VipsIntent, rendering intent
Make a thumbnail from a file. Shrinking is done in three stages: using any shrink-on-load features available in the file import library, using a block shrink, and using a lanczos3 shrink. At least the final 200% is done with lanczos3. The output should be high quality, and the operation should be quick.
See vips_thumbnail_buffer()
to thumbnail from a memory source.
The output image will fit within a square of size width
x width
. You can
specify a separate height with the height
option.
If you set crop
, then the output image will fill the whole of the width
x
height
rectangle, with any excess cropped away. See vips_smartcrop()
for
details on the cropping strategy.
Normally the operation will upsize or downsize as required to fit the image
inside or outside the target size. If size
is set
to VIPS_SIZE_UP, the operation will only upsize and will just
copy if asked to downsize.
If size
is set
to VIPS_SIZE_DOWN, the operation will only downsize and will just
copy if asked to upsize.
If size
is VIPS_SIZE_FORCE, the image aspect ratio will be broken and the
image will be forced to fit the target.
Normally any orientation tags on the input image (such as EXIF tags) are
interpreted to rotate the image upright. If you set auto_rotate
to FALSE
,
these tags will not be interpreted.
Shrinking is normally done in sRGB colourspace. Set linear
to shrink in
linear light colourspace instead. This can give better results, but can
also be far slower, since tricks like JPEG shrink-on-load cannot be used in
linear space.
If you set export_profile
to the filename of an ICC profile, the image
will be transformed to the target colourspace before writing to the
output. You can also give an import_profile
which will be used if the
input image has no ICC profile, or if the profile embedded in the
input image is broken.
Use intent
to set the rendering intent for any ICC transform. The default
is VIPS_INTENT_RELATIVE.
See also: vips_thumbnail_buffer()
.
Parameters
filename |
file to read from |
|
out |
output image. |
[out] |
width |
target width in pixels |
|
... |
|
vips_thumbnail_buffer ()
int vips_thumbnail_buffer (void *buf
,size_t len
,VipsImage **out
,int width
,...
);
Optional arguments:
height
:gint
, target height in pixelssize
: VipsSize, upsize, downsize, both or forceauto_rotate
:gboolean
, rotate upright using orientation tagcrop
: VipsInteresting, shrink and crop to fill targetlinear
:gboolean
, perform shrink in linear lightimport_profile
:gchararray
, fallback import ICC profileexport_profile
:gchararray
, export ICC profileintent
: VipsIntent, rendering intent
Exacty as vips_thumbnail()
, but read from a memory buffer.
See also: vips_thumbnail()
.
Parameters
buf |
memory area to load. |
[array length=len][element-type guint8] |
len |
size of memory area. |
[type gsize] |
out |
output image. |
[out] |
width |
target width in pixels |
|
... |
|
vips_thumbnail_image ()
int vips_thumbnail_image (VipsImage *in
,VipsImage **out
,int width
,...
);
Optional arguments:
height
:gint
, target height in pixelssize
: VipsSize, upsize, downsize, both or forceauto_rotate
:gboolean
, rotate upright using orientation tagcrop
: VipsInteresting, shrink and crop to fill targetlinear
:gboolean
, perform shrink in linear lightimport_profile
:gchararray
, fallback import ICC profileexport_profile
:gchararray
, export ICC profileintent
: VipsIntent, rendering intent
Exacty as vips_thumbnail()
, but read from an existing image.
See also: vips_thumbnail()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
width |
target width in pixels |
|
... |
|
vips_similarity ()
int vips_similarity (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
scale
:gdouble
, scale by this factorangle
:gdouble
, rotate by this many degrees clockwiseinterpolate
: VipsInterpolate, interpolate pixels with thisidx
:gdouble
, input horizontal offsetidy
:gdouble
, input vertical offsetodx
:gdouble
, output horizontal offsetody
:gdouble
, output vertical offsetody
:gdouble
, output vertical offsetbackground
: VipsArrayDouble colour for new pixels
This operator calls vips_affine()
for you, calculating the matrix for the
affine transform from scale
and angle
. Other parameters are passed on to
vips_affine()
unaltered.
See also: vips_affine()
, VipsInterpolate.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
... |
|
vips_affine ()
int vips_affine (VipsImage *in
,VipsImage **out
,double a
,double b
,double c
,double d
,...
);
Optional arguments:
interpolate
: VipsInterpolate, interpolate pixels with thisoarea
: VipsArrayInt, output rectangleidx
:gdouble
, input horizontal offsetidy
:gdouble
, input vertical offsetodx
:gdouble
, output horizontal offsetody
:gdouble
, output vertical offsetextend
: VipsExtend how to generate new pixelsbackground
: VipsArrayDouble colour for new pixels
This operator performs an affine transform on an image using interpolate
.
The transform is:
1 2 3 4 5 6 7 |
X = @a * (x + @idx) + @b * (y + @idy) + @odx Y = @c * (x + @idx) + @d * (y + @idy) + @doy where: x and y are the coordinates in input image. X and Y are the coordinates in output image. (0,0) is the upper left corner. |
The section of the output space defined by oarea
is written to
out
. oarea
is a four-element int array of left, top, width, height.
By default oarea
is just large enough to cover the whole of the
transformed input image.
By default, new pixels are filled with background
. This defaults to
zero (black). You can set other extend types with extend
. VIPS_EXTEND_COPY
is better for image upsizing.
interpolate
defaults to bilinear.
idx
, idy
, odx
, ody
default to zero.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_shrink()
, vips_resize()
, VipsInterpolate.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
a |
transformation matrix coefficient |
|
b |
transformation matrix coefficient |
|
c |
transformation matrix coefficient |
|
d |
transformation matrix coefficient |
|
... |
|
vips_resize ()
int vips_resize (VipsImage *in
,VipsImage **out
,double scale
,...
);
Optional arguments:
vscale
:gdouble
vertical scale factorkernel
: VipsKernel to reduce with
Resize an image.
When downsizing, the
image is block-shrunk with vips_shrink()
,
then the image is shrunk again to the
target size with vips_reduce()
. How much is done by vips_shrink()
vs.
vips_reduce()
varies with the kernel
setting. Downsizing is done with
centre convention.
vips_resize() normally uses VIPS_KERNEL_LANCZOS3 for the final reduce, you
can change this with kernel
.
When upsizing (scale
> 1), the operation uses vips_affine()
with
a VipsInterpolate selected depending on kernel
. It will use
VipsInterpolateBicubic for VIPS_KERNEL_CUBIC and above. It adds a
0.5 pixel displacement to the input pixels to get centre convention scaling.
vips_resize() normally maintains the image aspect ratio. If you set
vscale
, that factor is used for the vertical scale and scale
for the
horizontal.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See also: vips_shrink()
, vips_reduce()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
scale |
scale factor |
|
... |
|
vips_mapim ()
int vips_mapim (VipsImage *in
,VipsImage **out
,VipsImage *index
,...
);
Optional arguments:
interpolate
: interpolate pixels with this
This operator resamples in
using index
to look up pixels. out
is
the same size as index
, with each pixel being fetched from that position in
in
. That is:
1 |
out[x, y] = in[index[x, y]] |
If index
has one band, that band must be complex. Otherwise, index
must
have two bands of any format.
Coordinates in index
are in pixels, with (0, 0) being the top-left corner
of in
, and with y increasing down the image. Use vips_xyz()
to build index
images.
interpolate
defaults to bilinear.
This operation does not change xres or yres. The image resolution needs to be updated by the application.
See vips_maplut()
for a 1D equivalent of this operation.
See also: vips_xyz()
, vips_affine()
, vips_resize()
,
vips_maplut()
, VipsInterpolate.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
index |
index image |
|
... |
|
vips_quadratic ()
int vips_quadratic (VipsImage *in
,VipsImage **out
,VipsImage *coeff
,...
);
Optional arguments:
interpolate
: use this interpolator (default bilinear)
This operation is unfinished and unusable, sorry.
See also: vips_affine()
.
[method]
Parameters
in |
input image |
|
out |
output image. |
[out] |
coeff |
horizontal quadratic |
|
... |
|
Types and Values
enum VipsSize
Controls whether an operation should upsize, downsize, both up and downsize, or force a size.
See also: vips_thumbnail()
.