ImageGear Professional

Java Class Library User’s Guide

 

 

© 2002 AccuSoft Corporation. All Rights Reserved. AccuSoft and ImageGear are registered trademarks of AccuSoft Corporation. The AccuSoft Image Guaranteeä , Pro Gold, and High Performance Imaging™ are trademarks of AccuSoft Corporation. All company and brand names are trademarks or registered trademarks of their respective owners.

Welcome to ImageGear Java

ImageGear Java comes in two versions, a Java Class Library for access to low-level programming functions, and a Java Beans toolkit for higher-level programming.

ImageGear Java includes:

 

Overview

ImageGear Java consists of four packages:

accusoft.ig

Contains public classes that provide the product's functionality.

accusoft.ig.core

Contains internal classes not supposed to be used directly by applications.

accusoft.ig.GUI

Contains public components that provide a graphical user interface for product functionality.

accusoft.ig.Bean

Contains Bean implementation.

 

ImageGear Java includes a set of samples that demonstrates how to use IG functionality.

There are 2 samples:

 

Accusoft.ig Package Overview

This package contains all public interfaces and the product's functionality. It includes three groups of classes: interfaces, containers, and static API.

Interfaces

Interface declarations are logical definitions for objects whose exact type is not fixed during program execution. The following table lists these declarations.

Interface

Definition

IG_Instance

IG_Instance defines an interface for an object that contains all product parameters and options.

IG_IDIB

IG_DIB defines an interface for a DIB container. A DIB (Device Independent Bitmap) contains the information that defines a digital image.

IG_IError

IG_Ierror defines an interface for the error stack. The error stack is an object that collects information about all errors and warnings that occurs during an operation.

IG_IversionControl

IG_IversionControl defines an interface for version control. All IG classes implement this interface.

IG_Status

IG_Status defines an interface that controls most pixel transformation operations.This mechanism provides the ability to set a class thatwhich receives status events from a monitored operation. It is described inwith more details in the javadoc module.

 

Container Overview

Class containers store data.

Here is brief description for these classes.

Container

Description

Gear_Page

Gear_Page encapsulates a single page of a multi-page image. This object contains one or more DIB objects that stores pixel data, and provides synchronization for multi-thread use.

IG_CDibHeader

IG_CDibHeader contains the header information of a DIB object, for example, width, height, color resolution, and other parameters.

IG_CResolution

IG_Cresolution contains resolution data and is included in the IG_CdibHeader object as one of the DIB parameters.

IG_CScrollInfo

IG_CScrollInfo contains scroll parameters: scroll range and position. This information is used in the display code to set and get scroll parameters.

IG_StatusInfo

IG_StatusInfo contains low-level status bar parameters. This information is used in operations to calculate progress values.

 

 

Public API Overview

This group contains classes that implement public static methods. This allows class containers to manipulate using-defined interfaces. Here is brief description for the classes from the API group. Check the appropriate JavaDoc description for detailed information.

Public API

Definition

IG_PageAccess

The IG_PageAccess API allows the setting and getting parameters of a Gear_Page object. This API provides multithread support.

IG_PageIO

The IG_PageIO API provides input and output stream operations, for example, opening a stream and performing read/write operations.

IG_PageLoad

The IG_PageLoad API provides load and import operations, and accesses related parameters. This class contains functions for loading an image, its header, and receiving information about pages.

IG_PageWrite

The IG_PageWrite API provides writing and export operations, for example, inserting a new page into multi-page file.

IG_PageDisplay

The IG_PageDisplay API displays and prints a page.

IG_PageIP

The IG_PageIP API provides image processing implementation, for example, rotate, resize, crop and flip.

IG_Utils

The IG_Utils provides various useful utilities.

 

Please see complete API reference at:

Packages

 

Licensing

After the ImageGear Professional installation you need to obtain license key.

If you're evaluating the product please use AccuSoft ImageGear evaluation page (https://www.accusoft.com/licensing/v1/WebEvalClient/product.aspx). Please login using the same e-mail and password you have registered with on AccuSoft Web site. After you supply login credentials your license key will be automatically generated and displayed in the browser’s window. You can copy and paste it into your application.

Evaluation license enables you to use any features of the product on your machine for a limited period of time.

To extend Evaluation license:

1. Login to the AccuSoft ImageGear evaluation page.

2. Click Submit extension request button.

Your request will be considered and you will receive e-mail notification when your license is extended. Then you would need to login to the AccuSoft ImageGear evaluation page again to generate new license key.

If you have bought development copy of ImageGear Professional please use AccuSoft license page for developers (https://www.accusoft.com/licensing/v1/WebProductClient/login.aspx). You will be prompted to login using e-mail and password you have registered with on AccuSoft Web site. Upon login you will be presented with the page that has the combo-box containing different access keys for the AccuSoft products you have bought and allows you to generate a development license for each access key. Once you generated the license you can copy and paste it into your application.

Development license enables you to use any of the ImageGear features on the limited number of computers.

Note:

If you don’t have Internet connection, please call AccuSoft at 1-508-351-9092.

Note:

Development license enables you to develop any applications but in order to deploy your ImageGear-based application you need to obtain a deployment license. Please contact AccuSoft when you’re ready to deploy your solution.

 

Using ImageGear Java

Use the ImageGear Java toolkit for image file format manipulations - image loading and saving, some image processing operations including resizing, rotation, low-level input, output stream operations, image storage manipulations, compressions, and synchronization using standard Java classes.

ImageGear Java's extendible design provides a method to deliver a public interface specification for developing low-level code including custom format filters and custom image storage.

All product functionality is accessible through the package accusoft.ig. The following steps illustrate how to use ImageGear Java.

  1. Use the ImageGear Java toolkit to import the accusoft.ig package into your program:

Example

import accusoft.ig;;

  1. Allocate the object that implements interface IG_Instance. The actual class name for this object depends upon the version of your product. A particular version contains information about available functionality, for example, available format filters, compressions, internal image representations, etc.

Example

Inst = IGUtils. AllocateInstance( app, null );

This object also contains parameters for different functions such as optimization parameters, control parameters for filters, custom filters, etc.

  1. The Instance object does not store any pixel data; it provides a flexible work environment for the product, and optimizes it for custom applications. Use the Method IG_Utils.AllocateInstance to allocate this object.

Example

Inst = IGUtils. AllocateInstance( app, null );

The Error stack is an important part of the toolkit. It collects error and warning messages for IG operations. There is a public API that allocates the error stack object. Most IG methods return an integer value representing the last error code, or zero if the operation completed successfully. Important error codes are enumerated; their descriptions are retrievable. Use IG_Utils.AllocateErrorStack to allocate the error object.

  1. Allocate the object of the Gear_Page class using the IG_PageAccess.Create method. This method handles a single page of a multi-page image and stores the square area of pixels (named as "DIB"), stores an unlimited number of alpha channel DIBs, and stores unlimited number of thumbnail DIBs.

Example

page = IG_PageAccess.Create( Inst, err );

The Gear_Page object is not accessible directly but it is possible to allocate and access it using the public API from the accusoft.ig package. All operations that are applicable to this object are divided into 3 groups:

The thread-dependent parameter ACCESS_MODE synchronize these operations. The ACCESS_MODE parameter has three values:

Thread-associated parameters are necessary to store the working context for each thread used by the Gear_Page object. The current Gear_Page’s design stores all parameters as thread-dependent. Low-level methods IG_PageAccess.SetOption and IG_PageAccess.GetOption access all parameters. However do not use them directly because a high-level method handles them automatically.

Component

Description

Input/Output Stream

Each thread may open a Gear_Page object for input/output by associating a stream with it. Use WRITE_ACCESS_MODE if a thread needs to load shared data from the stream; otherwise use READ_ACCESS_MODE.

It is possible to have a single thread that loads data and other threads that write data into an output stream simultaneously.

Use IG_PageAccess.GetAccess and IG_PageAccess.SetAccess to get and set the access mode for a Gear_Page object.

Read/Write filter

After a Gear_Page is opened for input/output operations, it is possible to perform import and export pixel data operations using the read and write filters.

A filter is a class or set of classes that allows reading/decoding pixel data from a file format to an internal representation (DIB), and then encodes/writes pixel data into an external file format.

Gear_Page detects the file format and allocates a read or write filter to handle operations, for example, header loading, pixel loading, pixel writing, inserting new page etc.

Methods from the IG_PageIO class, for example, Open to open a Gear_Page stream, Close to close a Gear_Page stream, Seek for seeking a stream, etc.

Format header

Depending on the operation, the DIB header has different meanings. An import operation sets this header with parameters of an external image and it is only informative in this case, but for export operations it is used as parameter of how to export internal pixels into external format.

For example, after loading the header of a TIFF file, this object contains all parameters of a raster image from that file. The pixel data is not loaded and an appropriate internal representation (DIB) is not allocated. This header and the header of the actual allocated DIB may be different, and in this case, IG automatically converts pixel data from the source (filter’s) format to the destination.

All related methods implement the IG_PageLoad class:

  • LoadHeader fills the Format header with information about the external image,
  • GetFormatName gets the format name,
  • GetFormatHeader gets a copy of format header,
  • GetFormatAlphaCount and GetFormatThumbnailCount get the number of alpha channels and thumbanails,
  • GetFormatAlphaHeader and GetFormatThumbnailHeader get the header of alpha channel or thumbnail.

Current page number and total number of pages.

This contains the current page number and total number of pages in a multi-page file. The current page number is used for import and export operations. When importing, it is the number of pages to load; when writing, it is the number of the page designating where to insert the new page.

It is assumed that the first page is number 0; this is default value. The total number of pages may or may not exist depending whether the GetPageCount operation has completed. This operation is expensive – it seeks the entire file. This operation is not performed automatically after stream opens. However, if this value is necessary for another operation, then it is calculated.

The IG_PageLoad.GetPageCount method calculates the number of pages in a file. IG_PageLoad.GetPageNumber gets the current page number. IG_PageLoad.SetPageNumber sets the current page number.

Status bar object

This object monitors pixel operations - loading, writing and transforming. This allows the customer to supply a class that implements the IG_Status interface and monitors necessary operations. Using this mechanism it is possible to break execution of monitored operations. Use IG_PageAccess.SetStatus and IG_PageAccess.GetStatus to set and get the status object.

Filter attributes

Each format filter has a special set of attributes defined by the format specification. These are low-level parameters and it is necessary to be familiar with the format specification to change them. During the header read operation, the filter fills this object with these attributes; during write operations, the filter takes these values and writes them into an external file.

AccuSoft is not responsible for the validity of a file when the filter attributes are changed. Use IG_PageLoad.GetAttribute and IG_PageWrite.SetAttribute to get and set the format attribute object.

Display/Print Parameters

Many parameters define how to display and print images to logical device. The method IG_PageDisplay.Display draws an image onto a component object and IG_PageDisplay.Print prints it.

 

Each DIB object included with Gear_Page has an associated header that contains all parameters of the DIB. Some of these parameters are: Width, Height, BitsPerPixel, Palette, and FormatName.

The DIB header is an independent object and exists without an associated DIB. It stores information about the DIB. For example, the format header is a thread-dependent parameter.

The IG_PageLoad class contains these methods:

 

 

Methods without "format" word, return a header of allocated DIBs currently stored in the Gear_Page object. If these DIBs do not exist then the headers do not exist. To set new DIB objects into the Gear_Page method, use IG_PageLoad.InitDib and IG_pageLoad.CreateDib. Use IG_PageLoad.DeleteDib to delete the current DIB. The WRITE_ACCESS_MODE is necessary for these operations.

 

Display Functionality

This toolkit provides flexible support for displaying an image with different options, for example, fit method, aspect ratio, zoom and scroll. The Gear_Page object contains all display parameters as thread-dependent; the same image is displayed or printed from more than one thread using different parameters in each thread.

The same Gear_Page object can display using different Components with different layouts. Display parameters are simple to use. They use default values allowing the image to display and print without setting them to any specific values.

Before considering display parameters, lets look at some definitions and rules that provide a better understanding about how the display code works.

 

 

 

The previous graphic represents the image in green and the logical area to display the image with gray. The following table provides definitions for this graphic.

ImageRect

The ImageRect defines the part of image used in all display operations. In other words, the area not inside ImageRect is ignored. This rectangle is calculated in image coordinates - (0,0) means the top-left pixel of the image and (width-1, height-1) means the bottom-right pixel.

IG_PageDisplay.GetImageRect and IG_PageDisplay.SetImageRect methods get and set the ImageRect parameter. The default value is the whole image. ImageRect can not be larger than the actual image and can not intersect on image boundaries.

DeviceRect

DeviceRect defines the logical area to display the image and calculates the device coordinates that are related to the current output device – component. (0,0) means top-left corner of component.

IG_PageDisplay.GetDeviceRect and IG_PageDisplay.SetDeviceRect get and set the device rectangle. The default value is null - the device rectangle is calculated automatically from the component size.

ClipRect

ClipRect is the rectangle that defines an area inside of a component where to draw the image. In other words, this is a clipping rectangle that tells which part of the component is allocated for drawing the image.

IG_PageDisplay.GetClipRect and IG_PageDisplay.SetClipRect get and set ClipRect. The default value is null – the whole component is used for drawing.

ARatio

Aratio is the relationship between the width and height of an image or rectangle. The aspect ratio can be fixed or not fixed. Fixed means the display code tries to preserve the specified aspect ratio; Not fixed means the ratio may change depending upon other parameters.

The method GetAspectRatioMode returns the current aspect ratio mode which can be either:

  • ASPECT_RATIO_FIXED or
  • ASPECT_RATIO_NOT_FIXED

 

GetAspectRatioValue returns the current aspect ratio value as a rational value (width/height).

SetAspectRatio sets a new aspect ration mode and value.

The default aspect ratio mode is ASPECT_RATIO_FIXED and value is 1/1.

FitMode

This parameter tells how to map an image to a device rectangle. Possible values are:

  • FIT_TO_WIDTH – scales image to fit the device rectangle’s width.
  • FIT_TO_HEIGHT – scales image to fit the device rectangle’s height.
  • FIT_TO_WINDOW – scales image to fit the device rectangle’s height and width. If the aspect mode is fixed it applies either to FIT_TO_WIDTH, or FIT_TO_HEIGHT to draw the image inside of the device rectangle keeping the specified aspect ratio.
  • FIT_TO_ACTUAL_SIZE – ignores the device rectangle’s width and height and does not scale the image.

Methods IG_PageDisplay.GetFitMethod and IG_PageDisplay.SetFitMethod get and set this value.

Default value is FIT_TO_WINDOW.

Centered

This flag specifies how to locate the image inside a device rectangle after applying the fit method and aspect mode. If this flag is set then the display code centers the image inside the device rectangle, otherwise, the image is located at the top-left corner.

Methods IG_PageDisplay.GetCenteredFlag and IG_PageDisplay.SetCenteredFlag get and set this value.

Default value is true.

ZoomValue

ZoomValue is a relationship between the size of the visual representation of an image and its actual size. It can be fixed or not fixed. If this value is fixed then the display code applies correction after the fit method, aspect ratio and centered is done to keep the specified zoom value.

There are 2 methods that allow getting and setting this value:

  • IG_PageDisplay.GetZoomValue and
  • IG_PageDisplay.SetZoomValue

The default value is null - the zoom value is not fixed.

ScrollPos

If the image is not fit to ClipRect, then the scroll position is used to move the viewed area inside of the ClipRect. ImageGear automates scrolling by handling standard Scrollbar messages. It is necessary to attach a scrollbar to Gear_Page object using IG_PageDisplay.SetScrollBar method.

However, it is possible to obtain scroll parameters using the method IG_PageDisplay.GetScrollInfo. This sets the scroll position using the method IG_PageDisplay.SetScrollPos. The IG_PageDisplay.GetScrollInfo and IG_PageDisplay.SetScrollPos methods are useful even if the scrollbars are not attached.

ADeviceRect is a rectangle that is calculated using all the parameters described in the table. Its sense is "actual device rectangle" where the image completely fits by width and height.

 

List of file formats and compression algorithms supported in this version:

Read:

 

Important note: The AccuSoft Image Guaranteeä works for all supported formats listed above, except GIF and JPEG, where Java’s API is used to read those and therefore AccuSoft can not guarantee the correct reading of these.

 

Write:

 

ASCII Text Control Parameters

"XDpi" - Horizontal resolution of image. Type: Integer. Default: 200.

"YDpi" - Vertical resolution of image. Type: Integer. Default: 200.

"MarginsLeft" - Left text margin on page, expressed as thousandths of an inch. Type: Integer. Default: 1000.

"MarginsRight" - Right text margin on page, expressed as thousandths of an inch. Type: Integer. Default: 1000.

"MarginsTop" - Top text margin on page, expressed as thousandths of an inch. Type: Integer. Default: 1000.

"MarginsBottom" - Bottom text margin on page, expressed as thousandths of an inch. Type: Integer. Default: 1000.

"TabStop" - The number of characters per tab. Type: Integer. Default: 3.

"PageWidth" - Width of resulting page, expressed as thousandths of an inch. Type: Integer. Default: 8500.

"PageHeight" - Height of resulting page, expressed as thousandths of an inch. Type: Integer. Default: 11000.

"TypeFace" - Font metric:typeface name of the font. Type: String. Default: "Courier".

"Italic" - Font metric: if true use italic font. Type: Boolean. Default: false.

"Bold" - Font metric: if true use bold font. Type: Boolean. Default: false.

"PointSize" - Font metric: If 0 then lines per page or character per line is used, else - specifies font size. Type: Integer. Default: 10.

"LinesPerPage" - Number of lines per page. Used when PointSize is set to 0. Type: Integer. Default: 0.

"CharsPerLine" - Number of characters per line. Used when PointSize and LinesPerPage are set to 0. Type: Integer. Default: 0.

NOTE: "CharsPerLine" parameter is supposed to be used for monospace fonts, like "Courier". Using it with non-monospace fonts could produce not precisely right results.