gif-engine-js

Really basic JavaScript library written in ECMAScript 2017 for parsing GIF
(/gɪf/ not /ˈdʒɪf/) files.

Usage

fetch("//url.to/my.gif") /* request for a GIF file, can also be a filesystem
                          * read if you use Node or similar */
    .then(GIF)
    .then(async (gifObj) => {
      // code to manipulate raw GIF data

      const inflatedFrameData = await gifObj.inflate(0);
      /* returns an array containing decompressed color codes of the first
       * frame and also expands the frame's object with this array
       * gifObj.frames[0].data === inflatedFrameData => true */

      const deinterlacedFrameData = await gifObj.deinterlace(0);
      /* returns an array containing deinterlaced color codes of the first
       * frame and also expands the frame's object with this array
       * gifObj.frames[0].deinterlacedData === deinterlacedFrameData => true
       *
       * please note that you can call this function without calling
       * .inflate() first, because it will call it for you when the `data`
       * property is missing */

      const imageData = await gifObj.toImageData(0);
      /* returns an ImageData object ready to be used in a <canvas>
       * using this will NOT extend gifObj.frames[0] with an properties
       *
       * please note that you can call this function without calling
       * .inflate() first *and .deinterlace() if necessary*, because it
       * will call them for you when necessary */
    })

You'll notice that the Response object can be passed directly to the GIF
function. This is because GIF has a property (GIF.Response) which will be
checked using instanceof against the first argument. If it matches, then the
[GIF.responseMethod] method of the input will be called, which is by default
arrayBuffer, to compliment fetch in the browsers perfectly. Obviously, you
may change this as you wish depending on what you use to make requests.

Motivation

I needed a versatile library to process GIFs for personal use, but the already
available libraries out there all came with extra fluff that made it look
difficult to achieve what I wanted using them.

Return object

GIF will resolve into an Object if successfull. Will be referenced
as gifObj from here on out. Please do note that a gifObj contains function
methods and Symbol properties, so structured clone algorithm will fail to
copy it properly to a worker. Importing the library into a worker itself is
recommended instead.

Methods of a GIF object

These methods are, non-enumerable, non-configurable and non-writeable properties
of gifObj. They are also asynchronous, non-generic functions that will throw
if this is not a gifObj.

inflate: accepts two parameters index, ?clearRawData

index: index of the frame to be processed, must be an int bigger than 0,
will throw otherwise
?clearRawData: if this parameter is set to any truthy value, then the
rawData property of gifObj.frames[index] will be set to void 0

Returns an Array containing the LZW decompressed color codes
of the frame and expands gifObj.frames[index] with this array to the data
property.
deinterlace: accepts two parameters index, ?overwriteData

index: index of the frame to be processed, must be an int bigger than 0,
will throw otherwise
?overwriteData: if this parameter is set to any truthy value, then the
data property of gifObj.frames[index] will be overwritten with the result

Returns an Array containing the deinterlaced color codes
of the frame and expands gifObj.frames[index] with this array to the
deinterlacedData property. If overwriteData is true, then data will
contain the result and deinterlacedData will be set to null. If the user
didn't use .inflate(), then this function will do that with the optional
parameter (clearRawData) set to true, to avoid needlessly taking up memory
space. This method will only be called if the user omitted preprocessing the
frames themselves.
toImageData: accepts one parameter index

index: index of the frame to be processed, must be an int bigger than 0,
will throw otherwise

Returns an Array with this structure: [ImageData, offsetLeft, offsetTop].
It is recommended to destructure this array as parameters like so
ctx.putImageData(...gifObj.toImageData(0)). If the user didn't use
.inflate() or .deinterlace() if needed, then this function will do that
with both optional parameters (clearRawData, overwriteData) set to true,
to avoid needlessly taking up memory space. These methods will only be called
if the user omitted preprocessing the frames themselves.

Properties of a GIF object

Property names are in line with the GIF specification, for more detailed
explanation follow the link. gifObj also contains 2 Symbol properties for
internal uses.

descriptor:
object containing the Logical Screen Descriptor - type: Object
- width:
  width of the GIF - type: uint16
- height:
  height of the GIF - type: uint16
- backgroundColorIndex:
  type: uint8
- pixelAspectRatio:
  type: uint8
- packed:
  the packed byte - type: Object
  - globalColorTableFlag:
    indicates whether a Global Color Table is present or not -
    type: int, 0 or 1
  - colorResolution:
    type: int
  - sortFlag:
    indicates whether the Global Color Table is sorted or not -
    type: int, 0 or 1
  - size:
    indicates the size of Global Color Table (2 ** ( size + 1 )) -
    type: int, 0-7
globalColorTable:
type: Array if globalColorTableFlag equals 1, otherwise undefined
individual colors are stored in Arrays with the length of 3
repeat:
number of times for the GIF to be repeated, where 0 means repeat forever -
type: uint8
frames:
array containing the frames of the GIF -
type: Array

Properties of frame object

The details of the frames are stored in an Object.

graphicExtension:
object containing the Graphics Control Extension - type: Object
- disposalMethod:
  type: int, 0-7
- userInputFlag:
  type: int, 0 or 1
- transparentColorFlag:
  type: int, 0 or 1
- delay:
  the duration of which the frame should be displayed for
  in milliseconds - type: int
- transparentColorIndex:
  type: uint8
descriptor:
object containing the Image Descriptor - type: Object
- left:
  offset of the Image Data from the left of the GIF - type: uint16
- top:
  offset of the Image Data from the top of the GIF - type: uint16
- width:
  width of the Image Data - type: uint16
- height:
  height of the Image Data - type: uint16
- packed:
  the packed byte - type: Object
  - localColorTableFlag:
    indicates whether a Local Color Table is present or not -
    type: int, 0 or 1
  - interlaceFlag:
    indicates whether the color codes are interlaced or not -
    type: int, 0 or 1
  - sortFlag:
    indicates whether the Local Color Table is sorted or not -
    type: int, 0 or 1
  - size:
    indicates the size of Local Color Table (2 ** ( size + 1 )) -
    type: int, 0-7
localColorTable:
type: Array if localColorTableFlag equals 1, otherwise undefined
individual colors are stored in Arrays with the length of 3
minCodeSize:
minimum code size required for color table building - type: uint8, 2-8
rawData:
contains the concatenated Image Data sub-blocks - type: Array,
will be undefined if you call .inflate(index, true)
individual bytes are stored as uint8s
data:
contains decompressed color codes - type: Array
if .inflate() was called, otherwise undefined
individual codes are stored as uint8s
deinterlacedData:
contains deinterlaced color codes - type: Array
if .deinterlace() was called or null if .deinterlace(index, true) was
called, otherwise undefined
individual codes are stored as uint8s

Example

See the project page on my GitHub Pages for an example usage.
Worker addition can be found in this Gist.

Sources

What's In A GIF - Bit by Byte - Very easy to understand and detailed blog
by Matthew Flickinger
gifuct-js - LZW and deinterlace by Matt Way

License

WTFPL

friendlyanon/gif-engine-js