I
Deprecated Image Object Types and Methods

For release 8.1.4 and earlier, Oracle8 Image Cartridge described a set of image object types and methods that are deprecated for release 8.1.5. A deprecated feature is a feature that ships on the software kit and is working for the current release; however, it will not be enhanced in a future release, and may become obsolete and deleted in the future. These deprecated features are described here for reference and to help you migrate your release 8.1.4 and earlier image applications to release 8.1.5 interMedia image applications. This appendix describes these deprecated image object types and methods.

These deprecated features consists of two object types:

ORDImgB supports images stored in an Oracle8 binary large object (BLOB)
ORDImgF supports images stored in an Oracle8 external binary file (BFILE)

The cartridge (release 8.1.4) includes the following functions and procedures:

Table I-1 Functions and Procedures

Function or Procedure	Description
checkProperties	Verifies the stored image attributes match the actual image.
copyContent	Creates a copy of an image in another BLOB (available only for BLOBs, and not BFILEs).
deleteContent	Deletes the image content.
getMimeType	Returns the MIME type of an image.
getCompressionFormat	Returns the type of compression used on the image.
getContent	Returns the BLOB or BFILE containing the image.
getContentFormat	Returns the format of the image.
getContentLength	Returns the size of the image in bytes.
getFileFormat	Returns the file type of an image.
getHeight	Returns the height of the image in pixels.
getWidth	Returns the width of the image in pixels.
process	Performs in-place image processing on a BLOB.
processCopy	Performs image processing while copying an image to another BLOB.
setProperties	Fills in the attribute fields of an image (ORDImgB or ORDImgF data type).

When you are storing or copying images in an ORDImgB object, you must first create an empty BLOB in the table. The examples in this chapter assume that the following table, ordimgtab, has been created to store three images. Three empty rows have been created as follows:


create table ordimgtab(col1 number, col2 ORDSYS.ORDImgB);

insert into ordimgtab values

  (1, ORDSYS.ORDImgB(empty_blob(), NULL, NULL, NULL, NULL, NULL, NULL));

insert into ordimgtab values

  (2, ORDSYS.ORDImgB(empty_blob(), NULL, NULL, NULL, NULL, NULL, NULL));

insert into ordimgtab values

  (3, ORDSYS.ORDImgB(empty_blob(), NULL, NULL, NULL, NULL, NULL, NULL));

commit;

When storing images in an ORDImgF object, you must populate the type with an initializer.


create table ordimgtab(col1 number,col2 ORDSYS.ORDImgF);

insert into ordimgtab values

  (1, ORDSYS.ORDImgF(bfilename

       ('ORDIMGDIR','jdoe.gif'),NULL,NULL,

        NULL,NULL,NULL,NULL));

The 'bfilename' argument 'ORDIMGDIR' is a directory referring to a file system directory. Note that the directory name in a bfilename constructor must be in uppercase. The following sequence creates a directory named ORDIMGDIR:


connect internal

create or replace directory ORDIMGDIR as '<myimage directory>';

grant read on directory ORDIMGDIR to <user-or-role> with grant option;

ORDImgB Object Type

The ORDImgB object type is used for basic storage and retrieval of image data within an Oracle database. This object type is defined as follows:


CREATE TYPE ORDImgB AS OBJECT

(

-- TYPE ATTRIBUTES

content             BLOB,

height              INTEGER,  

width               INTEGER,

contentLength       INTEGER,

fileFormat          VARCHAR2(64),

contentFormat       VARCHAR2(64),

compressionFormat   VARCHAR2(64),

--- METHOD DECLARATION

  MEMBER PROCEDURE copyContent(dest IN OUT NOCOPY BLOB),

  MEMBER PROCEDURE setProperties(SELF IN OUT ORDImgB),	

  MEMBER PROCEDURE process    (SELF    IN OUT ORDImgB,

                               command  IN     VARCHAR2)

  MEMBER PROCEDURE processCopy(command  IN     VARCHAR2,

                               dest     IN OUT NOCOPY BLOB)

  MEMBER FUNCTION  getMimeType RETURN VARCHAR2,

  MEMBER FUNCTION  getContent  RETURN BLOB, 

  MEMBER FUNCTION  getContentLength RETURN INTEGER,

  MEMBER PROCEDURE deleteContent (SELF IN OUT ORDImgB),

  MEMBER FUNCTION  getHeight   RETURN INTEGER,

  MEMBER FUNCTION  getWidth    RETURN INTEGER,

  MEMBER FUNCTION  getFileFormat RETURN VARCHAR2,

  MEMBER FUNCTION  getContentFormat RETURN VARCHAR2,

  MEMBER FUNCTION  getCompressionFormat RETURN VARCHAR2,

  MEMBER FUNCTION  checkProperties RETURN BOOLEAN

);

where:

content: is the stored image
height: is the height of the image in pixels
width: is the width of image in pixels
contentLength: is the size of the on-disk image file in bytes
fileFormat: is the file type of image (such as, TIFF, JFIF)
contentFormat: is the type of image (such as, monochrome, 8-bit grayscale)
compressionFormat: is the compression type of image

In PL/SQL, data is moved with the DBMS LOB package. From the client, data is moved using OCI LOB calls. The ORDImgB object type does not supply piece-wise routines for moving data.

ORDImgF Object Type

The ORDImgF object type is used for retrieval of image data stored in external files. BFILE images are assumed to be read-only and this is reflected in the member procedures defined on the object type.


CREATE TYPE ORDImgF AS OBJECT

(

-- TYPE ATTRIBUTES

content             BFILE,

height              INTEGER,  

width               INTEGER,

contentLength       INTEGER,

fileFormat          VARCHAR2(64),

contentFormat       VARCHAR2(64),

compressionFormat   VARCHAR2(64),



-- METHOD DECLARATION

MEMBER PROCEDURE copyContent(dest IN OUT NOCOPY BLOB),

MEMBER PROCEDURE setProperties(SELF IN OUT ORDImgF),

MEMBER PROCEDURE processCopy(command IN VARCHAR2,   

                             dest    IN OUT NOCOPY BLOB),

MEMBER FUNCTION  getMimeType RETURN VARCHAR2,

MEMBER FUNCTION  getContent  RETURN BFILE, 

MEMBER FUNCTION  getContentLength RETURN INTEGER, 

MEMBER FUNCTION  getHeight   RETURN INTEGER,

MEMBER FUNCTION  getWidth    RETURN INTEGER,

MEMBER FUNCTION  getFileFormat RETURN VARCHAR2,

MEMBER FUNCTION  getContentFormat RETURN VARCHAR2,  

MEMBER FUNCTION  getCompressionFormat RETURN VARCHAR2,  

MEMBER FUNCTION  checkProperties RETURN BOOLEAN



);

where:

content: is the stored image
height: is the height of the image in pixels
width: is the width of image in pixels
contentLength: is the size of the on-disk image file in bytes
fileFormat: is the file type of image (such as, TIFF, JFIF)
contentFormat: is the type of image (such as, monochrome, 8-bit grayscale)
compressionFormat: is the compression type of image

checkProperties Method

Format


checkProperties RETURN BOOLEAN;

Description

Verifies that the properties stored in attributes of the image object match the properties of the image stored in the BLOB or BFILE. This method should not be used for foreign images.

Parameters

none

Returns

BOOLEAN

Usage

Use this method to verify that the image attributes match the actual image.

Example

Check the image attributes.


imgb1            ORDSYS.ORDImgB;

properties_match BOOLEAN;

              

...

properties_match := imgb1.checkProperties;

copyContent Method

Format


copyContent (dest IN OUT NOCOPY BLOB);

Description

Copies an image without changing it.

Parameters

dest

The destination of the new image.

Usage

This method copies the image data into the supplied BLOB.

Example

Create a copy of the image in type image1 into a BLOB called myblob:


image1.copyContent(myblob);

deleteContent Method

Format


deleteContent;

Description

Deletes the contents of the image.

Parameters

none

Usage

Use this method to delete the contents of the image BLOB. This method works only with BLOBS, not BFILES.

Example

Delete the image.


imgb1  ORDSYS.ORDImgB;



...

imgb1.deleteContent;

getCompressionFormat Method

Format


getCompressionFormat RETURN VARCHAR2;

Description

Returns the compression type of an image. This method does not actually read the LOB, it is a simple accessor method that returns the value of the compressionFormat attribute.

Parameters

none

Returns

VARCHAR2

Usage

Use this method rather than accessing the compressionFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImgB or ORDImgF object.

Example

Get the compression type of an image:


imgb1             ORDSYS.ORDImgB;

compressionFormat VARCHAR2(64);



...

compressionFormat := imgb1.getCompressionFormat;

getContent Method

Format


getContent RETURN BLOB;

getContent RETURN BFILE;

Description

Returns the LOB locator of the BLOB or BFILE containing the image. This is a simple accessor method that returns the value of the content attribute.

Parameters

none

Returns

BLOB or BFILE, corresponding to how the image is stored.

Usage

Use this method rather than accessing the content attribute directly to protect yourself from potential changes to the internal representation of the ORDImgB or ORDImgF object.

Example

Get the LOB locator for an image:


imgb1   ORDSYS.ORDImgB;

content BLOB;

...

content := imgb1.getContent;

getContentFormat Method

Format


getContentFormat RETURN VARCHAR2;

Description

Returns the type of an image (such as monochrome or 8-bit grayscale). This method does not actually read the LOB, it is a simple accessor method that returns the value of the contentFormat attribute.

Parameters

none

Returns

VARCHAR2

Usage

Use this method rather than accessing the contentFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImgB or ORDImgF object.

Example

Get the type of an image:


imgb1         ORDSYS.ORDImgB;

contentFormat VARCHAR2(64);



...

contentFormat := imgb1.getContentFormat;

getContentLength Method

Format


getContentLength RETURN INTEGER;

Description

Returns the size of the on-disk image in bytes. This method does not actually read the LOB, it is a simple accessor method that returns the value of the contentLength attribute.

Parameters

none

Returns

INTEGER

Usage

Use this method rather than accessing the contentLength attribute directly to protect yourself from potential changes to the internal representation of the ORDImgB or ORDImgF object.

Example

Get the content length of an image:


imgb1         ORDSYS.ORDImgB;

contentLength INTEGER;



...

contentLength := imgb1.getContentLength;

getFileFormat Method

Format


getFileFormat RETURN VARCHAR2

Description

Returns the file type of an image (such as TIFF or JFIF). This method does not actually read the LOB, it is a simple accessor method that returns the value of the fileFormat attribute.

Parameters

none

Returns

VARCHAR2

Usage

Use this method rather than accessing the fileFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImgB or ORDImgF object.

Example

Get the file type of an image:


imgb1      ORDSYS.ORDImgB;

fileFormat VARCHAR2(64);



...

fileFormat := imgb1.getFileFormat;

getHeight Method

Format


getHeight RETURN INTEGER;

Description

Returns the height of an image in pixels. This method does not actually read the LOB, it is a simple accessor method that returns the value of the height attribute.

Parameters

none

Returns

INTEGER

Usage

Use this method rather than accessing the height attribute directly to protect yourself from potential changes to the internal representation of the ORDImgB or ORDImgF object.

Example

Get the height of an image:


imgb1  ORDSYS.ORDImgB;

height INTEGER;



...

height := imgb1.getHeight;

getMimeType Method

Format


getMimeType RETURN VARCHAR2;

Description

Returns the MIME (Multipurpose Internet Mail Extension) type of an image (such as image/jpeg or image/tiff). This method returns the MIME type based on the fileFormat of the image. See Appendix A for the MIME type associated with each supported file format.

Parameters

none

Returns

VARCHAR2

Usage

Use this method to obtain the MIME type of the image. The MIME type is required by Web browsers along with the image content. It tells the Web browser how to interpret the image content.

For unrecognized file formats, this method returns image/binary.

Example

Get the MIME type of an image:


imgb1      ORDSYS.ORDImgB;

mimeType   VARCHAR2(64);



...

mimeType := imgb1.getMimeType;

getWidth Method

Format


getWidth RETURN INTEGER;

Description

Returns the width of an image in pixels. This method does not actually read the LOB, it is a simple accessor method that returns the value of the width attribute.

Parameters

none

Returns

INTEGER

Usage

Use this method rather than accessing the width attribute directly to protect yourself from potential changes to the internal representation of the ORDImgB or ORDImgF object.

Example

Get the width of an image:


imgb1  ORDSYS.ORDImgB;

width  INTEGER;



...

width := imgb1.getWidth;

process Method

Format


process (command IN VARCHAR2 );

Description

Performs one or more image processing techniques on a BLOB, writing the image back on itself.

Parameters

command

A list of image processing changes to make for the image.

Usage

You can change one or more of the image attributes shown inTable I-2. Table I-3 shows additional changes that can be made only to raw pixel and foreign images. See Appendix A for information on all the supported format combinations. See Appendix C for a more complete description of each operator.

Table I-2 Image Processing Operators

Operator Name	Usage	Values
compressionFormat	compression type/format	JPEG, SUNRLE, BMPRLE, TARGARLE, LZW, LZWHDIFF, FAX3, FAX4, HUFFMAN3, Packbits, GIFLZW
compressionQuality	compression quality	MAXCOMPRATIO, MAXINTEGRITY, LOWCOMP, MEDCOMP, HIGHCOMP
contentFormat	image type/pixel/data format	MONOCHROME, 8 BITGRAYSCALE, 8 BITGREYSCALE, 8BITLUT, 24BITRGB,
cut	window to cut or crop (origin.x origin.y width height)	(Integer Integer Integer Integer) maximum value is 65535
fileFormat	file format of the image	BMPF, CALS, GIFF, JFIF, PICT, RASF, RPIX, TGAF, TIFF
fixedScale	scale to a specific size in pixels (width, height)	(INTEGER INTEGER)
maxScale	scale to a specific size in pixels, while maintaining the aspect ratio (maxWidth, maxHeight)	(INTEGER INTEGER)
scale	scale factor (for example, 0.5 or 2.0)	<FLOAT> positive
xScale	X-axis scale factor (default is 1)	<FLOAT> positive
yScale	Y-axis scale factor (default is 1)	<FLOAT> positive

Table I-3 Additional Image Processing Operators for Raw Pixel and Foreign Images

Operator Name	Usage	Values
ChannelOrder	Indicates the relative position of the red, green, and blue channels (bands) within the image.	RGB (default), RBG, GRB, GBR, BRG, BGR
InputChannels	For multiband images, specify either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third). Note that this parameter affects the source image, not the destination.	INTEGER or INTEGER INTEGER INTEGER
Interleave	Controls band layout within the image: Band Interleaved by Pixel Band Interleaved by Line Band Sequential	BIP (default), BIL, BSQ
PixelOrder	If NORMAL, then the leftmost pixel appears first in the image.	NORMAL (default), REVERSE
ScanlineOrder	If NORMAL, then the top scanline appears first in the image.	NORMAL (default), INVERSE

Note:
When specifying values that include floating-point numbers, you must use double quotation marks (" ") around the value. If you do not, this may result in incorrect values being passed and you will get incorrect results.

Examples

Change the file format of image1 to GIF:


image1.process('fileFormat=GIFF');

Change image1 to use lower quality JPEG compression and double the length of the image along the X-axis:


image1.process('compressionFormat=JPEG, compressionQuality=LOWCOMP, 

xScale="2.0"'); 

image1.setproperties;

Note that changing the length on only one axis (for example, xScale=2.0) does not affect the length on the other axis, and would result in image distortion. Also, only the xScale and yScale parameters can be combined in a single operation. Any other combinations of scale operators result in an error.

The maxScale and fixedScale operators are especially useful for creating thumbnail images from various-sized originals. The following line creates 32-by-32 pixel thumbnail image, preserving the original aspect ratio:


image1.process(maxScale="32 32");

processCopy Method

Format


processCopy (command IN VARCHAR2,

             dest IN OUT NOCOPY BLOB);

Description

Process an image BLOB or BFILE to another BLOB.

Parameters

command

A list of image processing changes to make for the image in the new copy.

dest

The destination of the new image.

Usage

See Table I-2, "Image Processing Operators" and Table I-3, "Additional Image Processing Operators for Raw Pixel and Foreign Images".

When using temporary LOBs, you cannot specify the same temporary LOB as both the source and destination.

Example

Copy an image, changing the file format, compression format, and data format in the destination image:


create or replace procedure copyit is 

  imgB1     ORDSYS.ORDImgB; 

  imgB4     ORDSYS.ORDImgB; 

  mycommand   VARCHAR2(400); 

begin 

  select col2 into imgB1 from ordimgtab  where col1 = 1; 

  select col2 into imgB4 from ordimgtab  where col1 = 4 for update; 

  command:= 'fileFormat=tiff compressionFormat = packbits 

  contentFormat = 8bitlut'; 

  imgB1.processcopy(mycommand,imgB4.content); 

  imgB4.setproperties;

  update ordimgtab set col2 = imgB4 where col1 = 4;

end;

setProperties Method

Format


setProperties( );

Description

Writes the characteristics of an image (BLOB or BFILE) into the appropriate attribute fields.

Parameters

none

Usage

After you have copied, stored, or processed a native format image, call this procedure to set the current characteristics of the new content.

This procedure sets the following information about an image:

Height in pixels
Width in pixels
Data size of the on-disk image in bytes
File type (TIFF, JFIF, and so forth)
Image type (monochrome, 8-bit grayscale, and so forth)
Compression type (JPEG, LZW, and so forth)

Example

Select the image, and then set the attributes using the setProperties method:


imgB1 ORDSYS.imgB;

.

.

.

select col2 into imgB1 from ordimgtab where col1 = 1 for update;

imgB1.setProperties;

dbms_output.put_line('image width = '|| imgB1.width );

dbms_output.put_line('image height = '|| imgB1.height );

dbms_output.put_line('image size = '|| imgB1.contentLength );

dbms_output.put_line('image file type = '|| imgB1.fileFormat );

dbms_output.put_line('image type = '|| imgB1.contentFormat );

dbms_output.put_line('image compression = '|| imgB1.compressionFormat );

Example output:


image width = 360

image height = 490

image size = 59650

image file type = JFIF

image type = 24BITRGB

image compression = JPEG

setProperties( ) Method for Foreign Images

Format


SetProperties(description IN VARCHAR2);

Description

Allows you to write the characteristics of a foreign image (BLOB or BFILE) into the appropriate attribute fields.

Parameters

description

Specifies the image characteristics to set for the foreign image.

Usage

After you have copied, stored, or processed a foreign image, call this method to set the characteristics of the new image content. Unlike the native image types described in Appendix B, foreign images either do not contain information on how to interpret the bits in the file or interMedia image does not understand the information. In this case, you must set the information explicitly.

You can set the following image characteristics for foreign images, as shown in Table I-4.

Table I-4 Image Characteristics for Headerless Files

Field	Data Type	Description
CompressionFormat	STRING	Value must be CCITTG3, CCITTG4, or NONE (default).
DataOffset	INTEGER	The offset allows the image to have a header that interMedia image does not try to interpret. Set the offset to ignore any potential header. The value must be a positive integer less than the LOB length. Default is zero.
DefaultChannelSelection	INTEGER	For multiband images, specify either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third).
Height	INTEGER	Height of the image in pixels. Value must be a positive integer. There is no default, and a value must be specified.
Interleaving	STRING	Band layout within the image. Valid styles are: BIP (default) Band Interleaved by Pixel BIL Band Interleaved by Line BSQ Band Sequential
NumberOfBands	INTEGER	Value must be a positive integer less than 255 describing the number of color bands in the image. Default is 3.
PixelOrder	STRING	If NORMAL (default), the leftmost pixel appears first in the file. If REVERSE, the rightmost pixel appears first.
ScanlineOrder	STRING	If NORMAL (default), the top scanline appears first in the file. If INVERSE, then the bottom scanline appears first.
UserString	STRING	A 4-character descriptive string. If used, the string is stored in the fileFormat field, appended to the file format ("OTHER:"). Default is blank.
Width	INTEGER	Width of the image in pixels. Value must be a positive integer. There is no default, and a value must be specified.

The values supplied to setProperties( ) are written to the existing ORDImgB and ORDImgF object attributes. The fileFormat is set to "OTHER:" and includes the user string, if supplied.

Example

Select the image type, and then set the attributes using the setProperties method.


imgB1 ORDSYS.ORDIMgB;

select col2 into imgB1 from ordimgtab where col1 = 1 for update;

imgB1.setProperties('width=380 height=407 dataOffset=128 bandOrder=BIL


     userString="LSAT"');

I Deprecated Image Object Types and Methods

Table I-1 Functions and Procedures

ORDImgB Object Type

ORDImgF Object Type

checkProperties Method

Format

Description

Parameters

Returns

Usage

Example

copyContent Method

Format

Description

Parameters

Usage

Example

deleteContent Method

Format

Description

Parameters

Usage

Example

getCompressionFormat Method

Format

Description

Parameters

Returns

Usage

Example

getContent Method

Format

Description

Parameters

Returns

Usage

Example

getContentFormat Method

Format

Description

Parameters

Returns

Usage

Example

getContentLength Method

Format

Description

Parameters

Returns

Usage

Example

getFileFormat Method

Format

Description

Parameters

Returns

Usage

Example

getHeight Method

Format

Description

Parameters

Returns

Usage

Example

getMimeType Method

Format

Description

Parameters

Returns

Usage

Example

getWidth Method

Format

Description

Parameters

Returns

Usage

Example

process Method

I
Deprecated Image Object Types and Methods