Table of Contents

Class GifImage

Namespace
Aspose.Imaging.FileFormats.Gif
Assembly
Aspose.Imaging.dll

The API for Graphical Interchange Format (GIF) image file provides developers with versatile tools for processing compressed raster images and animated GIFs. Offering features like XMP metadata handling, color palette settings, background and transparent color control, opacity settings, resize, crop, filter application, gamma corrections, contrast adjustment, grayscale transformation, and conversion to other formats. This API empowers seamless manipulation and enhancement of GIF images for a wide range of applications.

public sealed class GifImage : RasterCachedMultipageImage, IDisposable, IObjectWithBounds, IRasterImageArgb32PixelLoader, IRasterImageRawDataLoader, IHasXmpData, IHasMetadata, IMultipageImageExt, IMultipageImage
Inheritance
GifImage
Implements
Inherited Members

Constructors

GifImage(GifFrameBlock)

Crafting GIF images becomes effortless with the GifImage constructor. With just the firstFrame parameter, it enters in a world of dynamic visual communication.

public GifImage(GifFrameBlock firstFrame)

Parameters

firstFrame GifFrameBlock

The first frame to initialize gif image with.

Exceptions

ArgumentNullException

The firstFrame cannot be null

ArgumentException

The firstFrame already belongs to some other image. Check the Container property.

GifImageException

The palette specified must contain entries count equal to power of 2. Minimal palette size is 2, maximal is 256.

GifImage(GifFrameBlock, IColorPalette)

Initiate a new GifImage object with specified parameters for the first frame and global palette. Start managing GIF images swiftly, ensuring accurate representation with customizable settings for optimal results.

public GifImage(GifFrameBlock firstFrame, IColorPalette globalPalette)

Parameters

firstFrame GifFrameBlock

The first frame to initialize gif image with.

globalPalette IColorPalette

The global palette to use. Note if both firstFrame and globalPalette are null then default global palette is used.

Exceptions

ArgumentNullException

The firstFrame cannot be null

ArgumentException

The firstFrame already belongs to some other image. Check the Container property.

GifImageException

The globalPalette specified should contain entries count equal to power of 2. Minimal palette size is 2, maximal is 256.

GifImage(GifFrameBlock, IColorPalette, bool, byte, byte, byte, bool)

Get started effortlessly with the GifImage constructor. With this simple method, you can dive into creating animated GIFs with ease. Just supply the firstFrame, globalPalette, paletteColorResolution, aspectRatio, and other parameters, and you're ready to bring your visuals to life.

public GifImage(GifFrameBlock firstFrame, IColorPalette globalPalette, bool isPaletteSorted, byte paletteColorResolution, byte paletteBackgroundColorIndex, byte aspectRatio, bool hasTrailer)

Parameters

firstFrame GifFrameBlock

The first frame to initialize gif image with.

globalPalette IColorPalette

The global palette to use. Note if both firstFrame and globalPalette are null then default global palette is used.

isPaletteSorted bool

if set to true the palette is sorted. Note the parameter is used when globalPalette is not null.

paletteColorResolution byte

The palette color resolution. Note the parameter is used when globalPalette is not null.

paletteBackgroundColorIndex byte

The palette background color index.

aspectRatio byte

The aspect ratio.

hasTrailer bool

if set to true the gif image has trailer otherwise no trailer written at the end of the stream.

Exceptions

ArgumentNullException

The firstFrame cannot be null

ArgumentException

The firstFrame already belongs to some other image. Check the Container property.

GifImageException

The globalPalette specified should contain entries count equal to power of 2. Minimal palette size is 2, maximal is 256.

Properties

ActiveFrame

Manage and manipulate frames with this property, enabling smooth navigation and modification of the active frame within the GIF image.

public GifFrameBlock ActiveFrame { get; set; }

Property Value

GifFrameBlock

The active frame.

BackgroundColor

Manage the background color of the GIF image with this property. You can set or retrieve the background color to ensure consistency and enhance visual appeal.

public override Color BackgroundColor { get; set; }

Property Value

Color

The background color.

BackgroundColorIndex

Control the background color index of the GIF image using this property. Set or retrieve the index to maintain consistency or achieve desired visual effects.

public byte BackgroundColorIndex { get; set; }

Property Value

byte

The background color index.

Blocks

Gain access to the GIF blocks seamlessly with this property, facilitating easy retrieval and manipulation of the image's underlying data structures.

public IGifBlock[] Blocks { get; }

Property Value

IGifBlock[]

FileFormat

Retrieve the file format effortlessly with this property. It's your go-to source for identifying the format of your files. Seamlessly integrated into your workflow, it provides vital information without any hassle.

public override FileFormat FileFormat { get; }

Property Value

FileFormat

HasBackgroundColor

This property determines whether the GIF image contains a background color. If true, it indicates that the image includes a background color.

public override bool HasBackgroundColor { get; }

Property Value

bool

HasTrailer

Manage the presence of a trailer in your GIF files with this property. Whether you need to check if a trailer exists or set its presence, this property simplifies the process. Keep your GIF files structured and compliant with this intuitive feature.

public bool HasTrailer { get; set; }

Property Value

bool

true if GIF has trailer; otherwise, false.

HasTransparentColor

Determine whether the active frame of the GIF image includes a transparent color. This property provides a convenient way to check for transparency within the image.

public override bool HasTransparentColor { get; set; }

Property Value

bool

ImageOpacity

Retrieve the opacity of the active frame within the image, offering insight into its transparency level. This property is particularly useful for understanding the degree of transparency or opaqueness of the active frame in the image.

public override float ImageOpacity { get; }

Property Value

float

The opacity value between 0.0 (fully transparent) and 1.0 (fully opaque).

IsInterlaced

Determines if the image is interlaced, impacting its display during loading. This property offers insight into the image's rendering behavior, essential for optimizing loading strategies and enhancing overall viewing experience.

public bool IsInterlaced { get; }

Property Value

bool

true if this image instance is interlaced; otherwise, false.

IsPaletteSorted

Control the sorting of the palette in your GIF images using this property. Whether you need to check if the palette is sorted or set the sorting behavior, this property provides a straightforward way to manage the palette organization in your GIF files.

public bool IsPaletteSorted { get; set; }

Property Value

bool

true if palette is sorted; otherwise, false.

LoopsCount

Retrieve the loop count effortlessly with this property. If your GIF image includes loop information, this property gives you quick access to the loop count, enabling you to seamlessly manage looping behavior in your GIF files.

public int LoopsCount { get; set; }

Property Value

int

The loops count or 1 (default value)

PageCount

Retrieve the total number of pages contained within the image with this straightforward property. Ideal for quickly assessing the extent of the image content.

public override int PageCount { get; }

Property Value

int

The page count.

PageExportingAction

This property enables the manipulation of the export action for the page, allowing to specify the desired action when exporting the page data. It provides flexibility in choosing export actions tailored to the needs of the application or workflow, enhancing customization and adaptability. Please note that setting this method will automatically release page resources after it is executed. It will be executed just before each page is saved.

public override PageExportingAction PageExportingAction { get; set; }

Property Value

PageExportingAction

The page exporting action.

Pages

Gain access to the pages within the image through this convenient property, allowing seamless navigation and manipulation of individual pages as needed.

public override Image[] Pages { get; }

Property Value

Image[]

The pages.

PaletteColorResolutionBits

Manage the palette color resolution of your GIF images with this property. Adjust the number of bits used to represent colors in the palette, providing fine control over color depth and image quality.

public byte PaletteColorResolutionBits { get; set; }

Property Value

byte

The palette color resolution bits.

PixelAspectRatio

Manage the pixel aspect ratio of the GIF image with this property. Set or retrieve the aspect ratio to ensure accurate rendering and maintain visual fidelity.

public byte PixelAspectRatio { get; set; }

Property Value

byte

The pixel aspect ratio.

TransparentColor

Retrieve the transparent color of the active frame in the GIF image. This property allows you to access the specific color that has been designated as transparent within the currently active frame.

public override Color TransparentColor { get; }

Property Value

Color

XmpData

Manage XMP metadata with this property. Whether you're retrieving existing metadata or updating it with new information, this property streamlines the process. Keep your metadata organized and accessible, ensuring that your files contain the relevant information they need.

public override XmpPacketWrapper XmpData { get; set; }

Property Value

XmpPacketWrapper

The XMP metadata.

Methods

AddBlock(IGifBlock)

Adding a new GIF block allows you to include additional data within the image. This method enables you to append custom blocks to the GIF image, which can contain various types of information.

public void AddBlock(IGifBlock block)

Parameters

block IGifBlock

The GIF block to add.

AddPage(RasterImage)

Incorporate a new page seamlessly into the existing image, enhancing its content and expanding its scope. This method augment image collections with additional content, fostering creativity and flexibility in image management and composition.

public void AddPage(RasterImage page)

Parameters

page RasterImage

The page to add.

Exceptions

ArgumentNullException

page is null.

AdjustBrightness(int)

Adjusts the brightness of the image according to the specified brightness parameter. This method modifies the brightness of the entire image uniformly, enhancing or reducing the overall luminance to achieve the desired effect.

public override void AdjustBrightness(int brightness)

Parameters

brightness int

Brightness value.

AdjustContrast(float)

Adjusts the contrast of the image, enhancing or reducing the difference in brightness between pixels. This method modifies the image's overall tonal range, making darker areas darker and brighter areas brighter to improve visual clarity and detail.

public override void AdjustContrast(float contrast)

Parameters

contrast float

Contrast value (in range [-100; 100])

Exceptions

ImageException

Can't change contrast. Frame index: " + frameIndex

AdjustGamma(float)

Enhance image quality by applying gamma correction. This method adjusts the color gamma of the image to achieve optimal visual clarity. It modifies the gamma value of each pixel, resulting in improved color rendition and overall image appearance.

public override void AdjustGamma(float gamma)

Parameters

gamma float

Gamma for red, green and blue channels coefficient

AdjustGamma(float, float, float)

Gamma-correction of an image applies a nonlinear adjustment to the pixel values, enhancing or reducing brightness based on the specified coefficients for the red, green, and blue channels. This method helps to fine-tune the color balance and luminance of the image, improving its overall appearance and visual quality.

public override void AdjustGamma(float gammaRed, float gammaGreen, float gammaBlue)

Parameters

gammaRed float

Gamma for red channel coefficient

gammaGreen float

Gamma for green channel coefficient

gammaBlue float

Gamma for blue channel coefficient

BinarizeBradley(double)

Binarization of an image using Bradley's adaptive thresholding algorithm with integral image thresholding is a method for converting a grayscale image into a binary image. This algorithm calculates a local threshold for each pixel based on the average intensity of the surrounding pixels within a specified window. By adaptively adjusting the threshold based on local pixel intensities, Bradley's method is effective at handling variations in lighting and contrast across the image.

public override void BinarizeBradley(double brightnessDifference)

Parameters

brightnessDifference double

The brightness difference between pixel and the average of an s x s window of pixels centered around this pixel.

BinarizeFixed(byte)

Binarization of an image with a predefined threshold converts a grayscale or color image into a binary image, where each pixel is classified as either black or white based on whether its intensity value exceeds a specified threshold.

public override void BinarizeFixed(byte threshold)

Parameters

threshold byte

Threshold value. If corresponding gray value of a pixel is greater than threshold, a value of 255 will be assigned to it, 0 otherwise.

BinarizeOtsu()

Binarization of an image with Otsu thresholding is a method used to automatically determine the optimal threshold value for converting a grayscale image into a binary image. The Otsu thresholding algorithm calculates the threshold that minimizes the intra-class variance of the pixel intensities in the two resulting classes (foreground and background). This technique is particularly useful when the optimal threshold value is unknown and needs to be determined adaptively based on the image's histogram.

public override void BinarizeOtsu()

ClearBlocks()

Clearing all the GIF blocks removes any existing data stored within the image. This operation effectively resets the image to an empty state, removing any previously added blocks. Use this method when you need to start fresh with a clean slate for creating or modifying a GIF image.

public void ClearBlocks()

Crop(Rectangle)

Crop the image using a specified rectangle area. This operation removes the outer portion of the image, leaving only the selected region defined by the rectangle.

public override void Crop(Rectangle rectangle)

Parameters

rectangle Rectangle

The rectangle.

Dither(DitheringMethod, int, IColorPalette)

Apply dithering to the current image. This process enhances image quality by reducing color banding and improving color transitions, resulting in a smoother appearance.

public override void Dither(DitheringMethod ditheringMethod, int bitsCount, IColorPalette customPalette)

Parameters

ditheringMethod DitheringMethod

The dithering method.

bitsCount int

The final bits count for dithering.

customPalette IColorPalette

The custom palette for dithering.

Filter(Rectangle, FilterOptionsBase)

Apply a specific filter to the designated area of the image, enhancing its visual quality or altering its appearance as desired. This method selectively processes pixels within the defined rectangle, allowing for targeted adjustments to be made while preserving the integrity of the surrounding image data.

public override void Filter(Rectangle rectangle, FilterOptionsBase options)

Parameters

rectangle Rectangle

The rectangle.

options FilterOptionsBase

The options.

GetOriginalOptions()

Retrieve the original file settings-based options, crucial for maintaining fidelity and consistency in image processing and manipulation. This method allows seamless integration of file-specific parameters into subsequent operations, ensuring accurate rendition and adherence to the image's inherent characteristics. This can be helpful to keep bit-depth and other parameters of the original image unchanged. For example, if we load a black-white PNG image with 1 bit per pixel and then save it using the Save(string) method, the output PNG image with 8-bit per pixel will be produced. To avoid it and save PNG image with 1-bit per pixel, use this method to get corresponding saving options and pass them to the Save(string, ImageOptionsBase) method as the second parameter.

public override ImageOptionsBase GetOriginalOptions()

Returns

ImageOptionsBase

The options based on the original file settings.

Grayscale()

The transformation of an image to its grayscale representation converts the color image into a grayscale version by removing color information while preserving luminance. This process simplifies the image to shades of gray, making it suitable for various applications such as printing, document processing, and grayscale analysis.

public override void Grayscale()

InsertBlock(int, IGifBlock)

Inserting a new GIF block allows you to add custom data at a specific position within the image. This method enables you to place custom blocks at a desired location in the GIF image, providing flexibility in organizing and structuring the image data.

public void InsertBlock(int index, IGifBlock block)

Parameters

index int

The zero-based element, at which block will be inserted.

block IGifBlock

The GIF block to add.

OnPaletteChanged(IColorPalette, IColorPalette) 

protected override void OnPaletteChanged(IColorPalette oldPalette, IColorPalette newPalette)

Parameters

oldPalette IColorPalette
newPalette IColorPalette

OnPaletteChanging(IColorPalette, IColorPalette) 

protected override void OnPaletteChanging(IColorPalette oldPalette, IColorPalette newPalette)

Parameters

oldPalette IColorPalette
newPalette IColorPalette

OrderBlocks()

Ordering the GIF blocks according to the GIF specification ensures proper GIF layout and compliance with the standard. This process involves arranging the blocks in the correct sequence as defined by the specification. Additionally, it may involve removing certain GifGraphicsControlBlock instances that are not necessary for the final layout. By adhering to the GIF specification, the resulting image will be correctly structured and compatible with GIF viewing applications.

public void OrderBlocks()

RemoveBlock(IGifBlock)

Removing a GIF block removes specific data from the image, offering the ability to clean up or modify the image structure. This method enables you to remove unwanted or unnecessary blocks, optimizing the GIF image for efficient storage. Use this functionality to eliminate outdated information from the image while preserving its integrity and quality.

public void RemoveBlock(IGifBlock block)

Parameters

block IGifBlock

The block to remove.

Remarks

Note: do not forget to Dispose the block if you will not add it to some other GifImage.

Resize(int, int, ImageResizeSettings)

Resize the width and height of the image while maintaining its aspect ratio and applying additional settings as specified. This method ensures that the image dimensions are adjusted proportionally, preserving the overall visual quality and appearance according to the provided settings.

public override void Resize(int newWidth, int newHeight, ImageResizeSettings settings)

Parameters

newWidth int

The new width.

newHeight int

The new height.

settings ImageResizeSettings

The resize settings.

Resize(int, int, ResizeType)

Modify the size of the image while maintaining its aspect ratio and visual quality. This function allows for easy adjustment of the image dimensions to suit specific display or storage needs, ensuring optimal presentation without distortion or loss of detail.

public override void Resize(int newWidth, int newHeight, ResizeType resizeType)

Parameters

newWidth int

The new width.

newHeight int

The new height.

resizeType ResizeType

The resize type.

ResizeFullFrame(int, int, ResizeType)

Resizing of the image while taking into account the full frames for each page in a GIF, thus preventing potential artifacts from appearing. This method is essential to maintain the integrity and quality of the image, especially when dealing with animated GIFs or sequences of frames.

public void ResizeFullFrame(int newWidth, int newHeight, ResizeType resizeType)

Parameters

newWidth int

The new width.

newHeight int

The new height.

resizeType ResizeType

The resize type.

ResizeProportional(int, int, ResizeType)

Proportional resizing maintains the aspect ratio of the image while adjusting its size, ensuring that the image does not appear stretched or distorted. This method resizes the image proportionally, scaling both the width and height by the same factor. The proportional resize will resize each frame according to the ratio of newWidth/width and newHeight/height.

public void ResizeProportional(int newWidth, int newHeight, ResizeType resizeType)

Parameters

newWidth int

The new width.

newHeight int

The new height.

resizeType ResizeType

The resize type.

Rotate(float, bool, Color)

This method rotates the image around its center point. By specifying the rotation angle, you can rotate the image clockwise or counterclockwise to achieve the desired orientation. This rotation helps adjust the image's presentation or alignment without distorting its content.

public override void Rotate(float angle, bool resizeProportionally, Color backgroundColor)

Parameters

angle float

The rotate angle in degrees. Positive values will rotate clockwise.

resizeProportionally bool

if set to true you will have your image size changed according to rotated rectangle (corner points) projections in other case that leaves dimensions untouched and only internal image contents are rotated.

backgroundColor Color

Color of the background.

RotateFlip(RotateFlipType)

Perform rotation, flipping, or both on the active frame exclusively. This operation applies transformations solely to the currently active frame of the image, preserving the integrity of other frames in the sequence.

public override void RotateFlip(RotateFlipType rotateFlipType)

Parameters

rotateFlipType RotateFlipType

The rotate flip type.

SaveData(Stream) 

protected override void SaveData(Stream stream)

Parameters

stream Stream

SetFrameTime(ushort)

Adjusts the duration of each frame in milliseconds, ensuring consistent timing throughout the image sequence. This method uniformly sets the display time for every frame, allowing for precise control over animation speed. Changing this value will reset delay for all frames.

public void SetFrameTime(ushort time)

Parameters

time ushort

The time of frame duration in milliseconds.

UpdateDimensions(int, int) 

protected override void UpdateDimensions(int newWidth, int newHeight)

Parameters

newWidth int
newHeight int