Vips.Image.new_from_file
Description: Reference for Vips.Image.new_from_file

### Constructor

# Vips Imagenew_from_file

#### Declaration [src]

    VipsImage*
    vips_image_new_from_file (
      const char* name,
      ...
    )

#### Description [src]

`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.

Optional arguments

- `access`: `VipsAccess`, hint expected access pattern
- `memory`: `gboolean`, force load via memory

See also

`vips_foreign_find_load()`, `vips_foreign_is_a()`, `vips_image_write_to_file()`.

This constructor is not directly available to language bindings.

#### Parameters

`name`

  Type: `const char*`

  File to open.

  The data is owned by the caller of the function.
  The value is a NUL terminated UTF-8 string.

`...`

  Type: ``

  `NULL`-terminated list of optional named arguments.

#### Return value

Type: `VipsImage`

The new `VipsImage`, or `NULL` on error.

The caller of the function takes ownership of the data, and is responsible for freeing it.