Skip to content

Home

Jump to bottom Edit New page
Brendan Duncan edited this page May 15, 2019 · 69 revisions

image is a Dart library providing the ability to load, save and manipulate images in a variety of different file formats.

The image library has no dependencies on dart:io or dart:html, so you can use the library for both server and web applications.

Supported Image Formats:

Read/Write:

  • PNG / Animated APNG
  • JPEG
  • Targa
  • GIF / Animated GIF

Read Only:

  • WebP / Animated WebP
  • TIFF
  • Photoshop PSD
  • OpenEXR

API

Examples

Filter Test

Format Decoding Functions

The following functions provide a high level interface for decoding images. You can also use the format specific Decoder classes to access format-specific data.

Generic Decoding Function

  • Image decodeImage(List<int> bytes);
    Decode an image, determining the format of the file by analyzing the bytes. If the file is an animated image, the first frame is decoded. Because this function has to determine the format of the image before it can decode it, it is preferable to use a format specific decoding function, such as decodeJpg, if you know what the format is.

    • bytes: The contents of the image file.
      Returns: the decoded Image.

  • Animation decodeAnimation(List<int> bytes);
    Decode a potentially animated image, determining the format of the file by analyzing the bytes. If the image isn't animated (a JPEG image, a non-animated GIF, etc), the returned Animation will contain a single frame containing the decoded image.

    • bytes: The contents of the image file.
      Returns: the decoded Animation.

  • Image decodeNamedImage(List<int> bytes, String name);
    Identify the format of the image using the file extension provided by [name], and decode it with the appropriate decoder.

    • bytes: The contents of the image file.
    • name: The name of the file (used to identify format from the file extension). Returns the decoded Image.

Format-Specific Decoding Functions

  • Image decodeGif(List<int> bytes);
    Decode a GIF formatted image. If the GIF is animated, the first frame is returned.

    • bytes: The contents of the GIF file.
      Returns: the decoded Image.

  • Animation decodeGifAnimation(List<int> bytes);
    Decode an animated GIF file. If the GIF isn't animated, the animation will contain a single frame with the GIF's image.

    • bytes: The contents of the GIF file.
      Returns: the decoded Animation.

  • Image decodeJpg(List<int> bytes);
    Decode a JPEG formatted image.

    • bytes: The contents of the JPEG file.
      Returns: the decoded Image.

  • Image decodePng(List<int> bytes);
    Decode a PNG formatted image. If the PNG is animated, the first frame is decoded.

    • bytes: The contents of the PNG file.
      Returns: the decoded Image.

  • Animation decodePngAnimation(List<int> bytes);
    Decode a PNG formatted animation. If the PNG isn't animated, the animation will contain a single frame with the PNG's image.

    • bytes: The contents of the PNG file.
      Returns: the decoded Animation.

  • Image decodePsd(List<int> bytes);
    Decode a Photoshop PSD formatted image.

    • bytes: The contents of the PSD file.
      Returns: the decoded Image.

  • Image decodeTga(List<int> bytes);
    Decode a Targa formatted image.

    • bytes: The contents of the TGA file.
      Returns: the decoded Image.

  • Image decodeWebP(List<int> bytes);
    Decode a WebP formatted image. If the WebP is animated ,the first frame is decoded.

    • bytes: The contents of the WebP file.
      Returns: the decoded Image.

  • Animation decodeWebPAnimation(List<int> bytes);
    Decode an animated WebP file. If the WebP isn't animated, the animation will contain a single frame with the WebP image.

    • bytes: The contents of the WebP file.
      Returns: the decoded Animation.

Format Encoding Functions

Generic Encoding Functions

  • List<int> encodeNamedImage(Image image, String name);
    Identify the format of the image and encode it with the appropriate encoder.
    • image: The image to encode.
    • name: The name of the image, used to derive the format to encode with from the extension.
      Returns: the encoded bytes.

Format-Specific Encoding Functions

  • List<int> encodeGif(Image image);
    Encode an image with the GIF format.

    • image: The image to encode.
      Returns: the encoded bytes.

  • List<int> encodeGifAnimation(Animation image);
    Encode an animation with the animated GIF format.

    • image: The animation to encode.
      Returns: the encoded bytes.

  • List<int> encodeJpg(Image image, {int quality: 100});
    Encode an image with the JPEG format.

    • image: The image to encode.
    • quality: The JPEG quality, in the range [0, 100] where 100 is highest quality.
      Returns: the encoded bytes.

  • List<int> encodePng(Image image, {int level: 6});
    Encode an image with the PNG format.

    • image: The image to encode.
    • level: The compression level, in the range [0, 9] where 9 is the most compressed.
      Returns: the encoded bytes.

  • List<int> encodeTga(Image image);
    Encode an image with the Targa format.

    • image: The image to encode.
      Returns: the encoded bytes.

Font / String Drawing Functions

  • Image drawChar(Image dst, BitmapFont font, int x, int y, String string, {int color: 0xffffffff});
    Draw a single character with the given font.
    Returns the modified image.

  • Image drawString(Image image, BitmapFont font, int x, int y, String string, {int color: 0xffffffff});
    Draw the string with the given font.
    Returns the modified image.
    Example, draw the string "Hello" starting at pixel 50,50, using the built-in 24-pt Arial font:
    drawString(image, arial_24, 50, 50, "Hello");

  • BitmapFont readFontZip(List<int> bytes);
    Load a BitmapFont from a zip file.
    Returns the decoded font.

  • BitmapFont readFont(String fnt, Image page);
    Load a BitmapFont from a font file and image.
    Returns the decoded font.

Image Filter / Modification Functions

Most filter functions modify images in-place, and return that image to make chaining functions easier. A few functions work on a copy of the input image, returning the modified copy. Those functions will be prefixed with the name 'copy'.

  • Image adjustColor(Image src, {int blacks, int whites, int mids, double contrast, double saturation, double brightness, double gamma, double exposure, double hue, double amount});
    Adjust the color of the [src] image using various color transformations.

    • src: The image to modify.
    • blacks: [todo document]
    • whites: [todo document]
    • mids: [todo document]
    • contrast: [todo document]
    • saturation: Scale the saturation of the image, where saturation 1.0 is the fully saturated color and saturation 0.0 is fully unsaturated (grayscale) color.
    • brightness: A linear multiplier for the RGB color values, brightens (> 1) or dims (< 0) the image. Default: 1.0.
    • exposure: an exponential multiplier for the RGB color values, as RGB *= pow(2, exposure). Default: 1.0.
    • gamma: An exponential multiplier for the RGB color values, as RGB = pow(RGB, gamma). A gamma > 1 darkens the image, and gamma < 1 brightens the image. Default: 1.0
    • hue: Offset the hue of the image, specified in degrees in the range [0, 360]. Default: 0.0
    • amount: The strength that this filter is applied to the image, where 1.0 indicates the filter has full effect, and 0.0 has no effect (the original image is returned unmodified). Default: 1.0.
      Returns: The modified [src] image.

  • Image brightness(Image src, int brightness);
    Adjust the brightness of the image (in place).
    Returns the modified image.

  • Image bumpToNormal(Image src, {double strength: 2.0});
    Generate a normal map from a height-field bump image.
    Returns a new image.

  • Image colorOffset(Image src, int red, int green, int blue, int alpha);
    _Apply an offset to the colors of the image (in place).
    Returns the modified image.

  • Image contrast(Image src, num contrast);
    Apply the Contrast convolution filter to the image (in place).
    Returns the modified image.

  • Image convolution(Image src, List<num> filter, num filterDiv, num offset);
    Apply a convolution filter to the image (in place).
    Returns the modified image.

  • Image copyCrop(Image src, int x, int y, int w, int h);
    Create a cropped copy of the image.
    Returns a new image.

  • Image copyInto(Image dst, Image src, {int dstX, int dstY, int srcX, int srcY, int srcW, int srcH, bool blend: true});
    Copy an area of the src image into dst.
    Returns the modified dst image.

  • Image copyResize(Image src, {int width = -1, int height = -1, Interpolation interpolation = Interpolation.nearest});
    Create a resized copy of the image.
    If width or height are -1, it will be calculated by maintaining the aspect ratio of the original image.
    Interpolation: nearest, linear, cubic
    Returns a new image.

  • Image copyRotate(Image src, num angle, {Interpolation interpolation = Interpolation.nearest});
    Returns a copy of the [src] image, rotated by [angle] degrees.
    Returns a new image.

  • Image drawCircle(Image image, int x0, int y0, int radius, int color);
    Draw a circle (in place).
    Returns the modified image.

  • Image drawImage(Image dst, Image src, {int dstX, int dstY, int srcX, int srcY, int srcW, int srcH, bool blend: true});
    Draw the src image onto dst.
    Returns the modified dst image.

  • Image drawLine(Image image, int x1, int y1, int x2, int y2, int color, {bool antialias = false, num thickness = 1});
    Draw a line (in place).
    Returns the modified image.

  • Image drawPixel(Image image, int x, int y, int color, [int opacity = 0xff]);
    Draw a single pixel into the image, applying alpha and opacity blending (in place).
    Returns the modified image.

  • Image drawRect(Image image, int x1, int y1, int x2, int y2, int color);
    Draw a rectangle (in place).
    Returns the modified image.

  • Image dropShadow(Image src, int hshadow, int vshadow, int blur, {int shadowColor = 0x000000a0});
    Create a drop-shadow effect.
    Returns a new image.

  • Image emboss(Image src);
    Apply the Emboss convolution filter (in place).
    Returns the modified image.

  • Image fill(Image image, int color);
    Fill the image with the given color (in place).
    Returns the modified image.

  • Image fillRect(Image src, int x1, int y1, int x2, int y2, int color);
    Fill a rectangle with the given color (in place).
    Returns the modified image.

  • List<int> findTrim(Image src, {int mode = TRIM_TRANSPARENT, sides = TRIM_ALL});
    Find the crop area to be used by the trim function.
    Returns the coordinates as [x, y, width, height].

  • Image flip(Image src, int mode);
    Flip the image with FLIP_HORIZONTAL, FLIP_VERTICAL, or FLIP_BOTH (in place).
    Returns the modified image.

  • Image gaussianBlur(Image src, int radius);
    Blur the image (in place).
    Returns the modified image.

  • Image grayscale(Image src);
    Convert the colors of the image to grayscale (in place).
    Returns the modified image.

  • Image invert(Image src);
    Invert the colors of the image (in place).
    Returns the modified image.

  • Image noise(Image image, double sigma, {int type = NOISE_GAUSSIAN, Math.Random random});
    Add random noise to pixel values (in place).
    Returns the modified image.

  • Image normalize(Image src, int minValue, int maxValue);
    Linearly normalize the pixel values of the image (in place).
    Returns the modified image.

  • Image pixelate(Image src, int blockSize, {int mode = PIXELATE_UPPERLEFT});
    Pixelate the image (in place).
    Returns the modified image.

  • Image quantize(Image src);
    Reduces the number of colors in the image to 256.
    Returns the modified image.

  • Image remapColors(Image src, {int red: RED, int green: GREEN, int blue: BLUE, int alpha: ALPHA});
    Remap the color channels of an image (in place).
    Returns the modified image.

  • Image sepia(Image src, {num amount: 0.8});
    Filter the image colors using sepia tone.
    Returns the modified image.

  • Image smooth(Image src, num w);
    Apply a smooth convolution filter to the image (in place).
    Returns the modified image.

  • Image sobel(Image src, {double amount: 1.0});
    Apply a sobel edge detection filter to the image (in place).

    • amount: The strength that this filter is applied to the image, where 1.0 indicates the filter has full effect, and 0.0 has no effect (the original image is returned unmodified). Default: 1.0.
      Returns: The modified [src] image.

  • Image vignette(Image src, {num start: 0.3, num end: 0.8, num amount: 0.8});
    Darkens the edges of the image using a elliptical vignette filter.
    Returns the modified image.

Add a custom sidebar
Clone this wiki locally