30jpeg Module

30.1Overview

The jpeg module provides measures to read/write image data in JPEG format. To utilize it, import the jpeg module using import function.

Below is an example to read a JPEG file: 

import(jpeg)
img = image('foo.jpeg')

30.2Exntension to Function's Capability

This module extends the capability of function image() and instance method image#write() so that they can read/write JPEG files.

When function image() is provided with a stream that satisfies the following conditions, it would recognize the stream as a JPEG file.

  • The identifier of the stream ends with a suffix ".jpeg", ".jpg" or ".jpe".
  • The stream data begins with a byte sequence "\xff\xd8" that means SOI (start of Image) marker in JPEG specification.

When instance method image#write() is provided with a stream that satisfies the following condition, it would write image data in JPEG format.

  • The identifier of the stream ends with a suffix ".jpeg", ".jpg" or ".jpe".

30.3jpeg.exif Class

30.3.1Overview

The jpeg.exif class provides EXIF information in a JPEG stream.

A jpeg.exif instance contains jpeg.ifd instances as properties named jpeg.exif#ifd0 and jpeg.exif#ifd1 that include a list of jpeg.tag instances. 

+-----------+             +----------+        +----------+
| jpeg.exif |ifd0, ifd1   | jpeg.ifd |1..     | jpeg.tag |
|-----------*-------------+----------*--------+----------|
|           |             |          |        |          |
+-----------+             +----------+        +----------+

30.3.2Property

A jpeg.exif instance has the following properties:

jpeg.exif#endian … boolean [read-only]
The endian type: `big for big-endian and `little for little-endian.
jpeg.exif#ifd0 … jpeg.ifd [read-only]
IFD0 instance.
jpeg.exif#ifd1 … jpeg.ifd [read-only]
IFD1 instance.
jpeg.exif#thumbnail … image [read-only]
Thumbnail image as image value.
jpeg.exif#thumbnail@jpeg … binary [read-only]
Thumbnail image as JPEG binary data.

30.3.3Constructor

jpeg.exif(stream?:stream:r):map:[raise] {block?}

Reads EXIF data from stream and creates a jpeg.exif instance.

If no EXIF information exists in the stream, this function returns nil. If the attribute :raise is specified, an error occurs for that case.

If block is specified, it would be evaluated with a block parameter |exif:jpeg.exif|, where exif is the created instance. In this case, the block's result would become the function's returned value.

30.3.4Method

jpeg.exif#each() {block?}

Creates an iterator that returns jpeg.tag values as elements that are stored in the property jpeg.exif#ifd0.

In default, this returns an iterator as its result value. Specifying the following attributes would customize the returned value:

  • :iter .. An iterator. This is the default behavior.
  • :xiter .. An iterator that eliminates nil from its elements.
  • :list .. A list.
  • :xlist .. A list that eliminates nil from its elements.
  • :set .. A list that eliminates duplicated values from its elements.
  • :xset .. A list that eliminates duplicated values and nil from its elements.

See the chapter of Mapping Process in Gura Language Manual for the detail.

If a block is specified, it would be evaluated repeatingly with block parameters |value, idx:number| where value is the iterated value and idx the loop index starting from zero. In this case, the last evaluated value of the block would be the result value. If one of the attributes listed above is specified, an iterator or a list of the evaluated value would be returned.

30.4jpeg.ifd Class

30.4.1Overview

30.4.2Property

A jpeg.ifd instance has the following properties:

jpeg.ifd#name … string [read-only]
jpeg.ifd#symbol … symbol [read-only]

30.4.3Method

jpeg.ifd#each() {block?}

Creates an iterator that returns jpeg.tag values as elements that are stored in the target jpeg.ifd instance.

In default, this returns an iterator as its result value. Specifying the following attributes would customize the returned value:

  • :iter .. An iterator. This is the default behavior.
  • :xiter .. An iterator that eliminates nil from its elements.
  • :list .. A list.
  • :xlist .. A list that eliminates nil from its elements.
  • :set .. A list that eliminates duplicated values from its elements.
  • :xset .. A list that eliminates duplicated values and nil from its elements.

See the chapter of Mapping Process in Gura Language Manual for the detail.

If a block is specified, it would be evaluated repeatingly with block parameters |value, idx:number| where value is the iterated value and idx the loop index starting from zero. In this case, the last evaluated value of the block would be the result value. If one of the attributes listed above is specified, an iterator or a list of the evaluated value would be returned.

30.5jpeg.tag Class

30.5.1Property

A jpeg.tag instance has the following properties:

jpeg.tag#id … number [read-only]
Tag ID.
jpeg.tag#ifd … undefined [read-only]
IFD instance. Valid only for tags Exif, GPSInfo and Interoperability.
jpeg.tag#name … string [read-only]
Tag name.
jpeg.tag#symbol … symbol [read-only]
Tag name as symbol.
jpeg.tag#type … number [read-only]
Tag type.
jpeg.tag#typename … string [read-only]
Tag type name.
jpeg.tag#value … any [read-only]
Tag value. When the attribute :cooked is specified, numbers in some tags are translated to human-readable symbols.

30.6Extension to image Class

This module extends the image class with methods described here.

image#read@jpeg(stream:stream:r, size?:number):reduce:[fast,rough]

Reads a JPEG image data from the specified stream.

When the argument size is specified, the image would be shrinked so that it is boxed within the size.

The attribute :fast indicates a fast but less-qualified decompression process.

The attriubte :rough is only valid when size is specified and makes the shrinked image with nearest neighbor method. Othereise, shrinking shall be done with bilinear method.

image#write@jpeg(stream:stream:w, quality:number => 75):reduce

Writes a JPEG image data to the specified stream.

The argument quality takes a number between 0 and 100 with which a a higher number results in a higher quality of result but a less compression performance. The default value for it is 75.

30.7Thanks

This module uses JPEG library which is distributed in the following site:

http://www.ijg.org/