Constructor
VipsImagenew_from_file
Declaration [src]
VipsImage*
vips_image_new_from_file (
const char* name,
...
)
Description [src]
Optional arguments
access: hintVipsAccessmode to loadermemory: force load via memory
vips_image_new_from_file() opens name for reading. It can load files
in many image formats, including VIPS, TIFF, PNG, JPEG, FITS, Matlab,
OpenEXR, CSV, WebP, Radiance, RAW, PPM and others.
Load options may be appended to filename as “[name=value,…]” or given as
a NULL-terminated list of name-value pairs at the end of the arguments.
Options given in the function call override options given in the filename.
Many loaders add extra options, see vips_jpegload(), for example.
vips_image_new_from_file() always returns immediately with the header
fields filled in. No pixels are actually read until you first access them.
access lets you set a VipsAccess hint giving the expected access pattern
for this file.
VIPS_ACCESS_RANDOM means you can fetch pixels randomly from the image.
This is the default mode. VIPS_ACCESS_SEQUENTIAL means you will
read the whole image exactly once, top-to-bottom. In this mode, libvips
can avoid converting the whole image in one go, for a large memory saving.
You are allowed to make small non-local references, so area operations like
convolution will work.
In VIPS_ACCESS_RANDOM mode, small images are decompressed to memory
and then processed from there. Large images are decompressed to temporary
random-access files on disc and then processed from there.
Set memory to TRUE to force loading via memory. The default is to load
large random access images via temporary disc files. 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 VIPS_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.
The default threshold is 100 MB.
For example:
VipsImage *image = vips_image_new_from_file("fred.tif",
"page", 12,
NULL);
Will open “fred.tif”, reading page 12.
VipsImage *image = vips_image_new_from_file("fred.jpg[shrink=2]",
NULL);
Will open fred.jpg, downsampling by a factor of two.
Use vips_foreign_find_load() or vips_foreign_is_a() to see what format a
file is in and therefore what options are available. If you need more
control over the loading process, you can call loaders directly, see
vips_jpegload(), for example.
This constructor is not directly available to language bindings.