ERDAS - Developers Toolkit Examples on-LineManual'

D e v e l o p e r s T o o l k i t E x a m p l e s '

O N - L I N E M A N U A L

Copyright 1982 - 1999 by ERDAS, Inc. All rights reserved.

Printed in the United States of America.

ERDAS Proprietary - Delivered under license agreement.Copying and disclosure prohibited without express written permission from ERDAS, Inc.

ERDAS, Inc.2801 Buford Highway, N.E.Atlanta, Georgia 30329-2137 USAPhone: 404/248-9000Fax: 404/248-9400User Support: 404/248-9777

WarningAll information in this document, as well as the software to which it pertains, is proprietary material of ERDAS, Inc., and issubject to an ERDAS license and non-disclosure agreement. Neither the software nor the documentation may be reproduced inany manner without the prior written permission of ERDAS, Inc.

Specifications are subject to change without notice.

TrademarksERDAS is a trade name of ERDAS, Inc. ERDAS and ERDAS IMAGINE are registered trademarks of ERDAS, Inc. ModelMaker, CellArray, ERDAS Field Guide, and ERDAS Tour Guides are trademarks of ERDAS, Inc. Other brands and productnames are trademarks of their respective owners.

DevelopersToolkitExamplesOn-LineManual'

iii

Purpose of the Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Reading and Writing ERDAS IMAGINE Files . . . . . . . . . . . . . . . . . . . . . . 1

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Introduction to Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Developers’ Toolkit Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Rules for using the Developers’ Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Toolkit Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Error Logging and Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Argument Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Raw Coordinate System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Map Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Units Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Radial Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Geographic Coordinates (Projections) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Image File Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

ERDAS IMAGINE .img Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

File Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Sensor Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Raster Layer Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Block Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Attribute Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25


iv

Continuous Raster Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Thematic Raster Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Map Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Map Projection Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Pyramid Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Reading and Writing .img Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

eerr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27emif . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27ehfa . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27edsc . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28eprj . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28esta . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28eimg . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28estr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28emap . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Hardcopy Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Roles of Map Composer, Mapmaker, and Printmanager . . . . . . . . . . . . . . . . . . . . . . . . . 29

Running Map Composer, Mapmaker, and Printmanager . . . . . . . . . . . . . . . . . . . . . . . . . 29

The Preference Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

The Device Setup Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

The Raster Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

The Installation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

User Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Machine Independent Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

MIF Data Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

EMIF_T_U1 (Unsigned 1-bit Integer). . . . . . . . . . . . . . . . . . . . . . . . . 46



EMIF_T_UCHAR (8-bit Unsigned Integer) . . . . . . . . . . . . . . . . . . . . . . 47

EMIF_T_CHAR (8-bit Signed Integer) . . . . . . . . . . . . . . . . . . . . . . . . 47

EMIF_T_USHORT (16-bit Unsigned Integer) . . . . . . . . . . . . . . . . . . . . . 47

EMIF_T_SHORT (16-bit Signed Integer) . . . . . . . . . . . . . . . . . . . . . . . 48

EMIF_T_ENUM (Enumerated Data Types) . . . . . . . . . . . . . . . . . . . . . . 48

EMIF_T_ULONG (32-bit Unsigned Integer). . . . . . . . . . . . . . . . . . . . . . 48


v

EMIF_T_LONG (32-bit Signed Integer) . . . . . . . . . . . . . . . . . . . . . . . 49

EMIF_T_PTR (32-bit Unsigned Integer) . . . . . . . . . . . . . . . . . . . . . . . 49

EMIF_T_TIME (32-bit Unsigned Integer). . . . . . . . . . . . . . . . . . . . . . . 50

EMIF_T_FLOAT (Single Precision Floating Point) . . . . . . . . . . . . . . . . . . . 50

EMIF_T_DOUBLE (Double Precision Floating Point). . . . . . . . . . . . . . . . . . 50

EMIF_T_COMPLEX (Single Precision Complex) . . . . . . . . . . . . . . . . . . . 51

EMIF_T_DCOMPLEX (Double Precision Complex) . . . . . . . . . . . . . . . . . . 51

EMIF_T_BASEDATA (Matrix of Numbers) . . . . . . . . . . . . . . . . . . . . . . 52

EMIF_M_INDIRECT (Indication of Indirect Data) . . . . . . . . . . . . . . . . . . . 54

EMIF_M_PTR (Indication of Indirect Data) . . . . . . . . . . . . . . . . . . . . . . 55

MIF Data Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

HFA Object Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Hierarchical File Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Nodes and Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Pre-defined HFA File Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Basic Objects of an HFA File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Ehfa_HeaderTag 62

Ehfa_File 62

Ehfa_Entry 63

Objects of a .img File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Eimg_Layer 66

Eimg_Layer_SubSample 67

Eimg_NonInitializedValue 68

Ehfa_Layer 68

RasterDMS 69

Edms_VirtualBlockInfo 70

Edms_FreeIDList 72

Edms_State 72

Edsc_Table 73

Edsc_BinFunction 73

Edsc_Column 74

Eded_ColumnAttributes_1 76

Esta_Statistics 78

Esta_Covariance 78

Esta_SkipFactors 79

Esta_ExcludedValues 79


vi

Eprj_Datum 79

Eprj_Spheroid 80

Eprj_ProParameters 80

Eprj_Coordinate 85

Eprj_Size 85

Eprj_MapInfo 85

Efga_Polynomial 86

Calibration_Node 87

External File Format Header Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

ADRG Header 89

ADRI Header 91

BandInfo Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

AVHRR Header 94

DEM Header 97

DOQ Header 100

DTED Header 105

MSS Header 107

TickMark Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

SPOT Header 112

struct SpotHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

GeoSpot Header Tablea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Spot Canadian Header Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

TM Header 133

Preference Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Installing, Compiling, and Running the Example Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Under Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Using the Example Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Compatibility Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Structure Packing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Under UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Example File Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145


vii

Example: read80descrip.c 147

Example: copy80layer.c 149

Example: RasterAccess.c 150

Example: display_anno.c 152

Example: draw_demo.c 153

Example: convolve.c 154

Example: canvas_test.c 155

Example: subset1.c 156


Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158


EML Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Example: readmssephemeris.c 162

Example: degrad.c 163

Example: digview.c 164

Example: eprj_sample.c 165

Example: fonttablemaker.c 166

Example: eemlsample.c 167

Example: table.c 168

Example: importex.c 169

Example: exportex.c 170

Example: chartdemo.c 171

Example: fxgeneral.c 172

Initialize the Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Determine the Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Open the Input Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Create the Output Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Allocate Pixel Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Read Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Modify the Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Write the Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Close the Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Create the Design For the Special Object . . . . . . . . . . . . . . . . . . . . . . . 177

Write the Object to the File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Example: imagecopy.c 178

1

Purpose of the Toolkit

Purpose of the Toolkit

The ERDAS Developers’ Toolkit is intended to allow outside developers to extend thecapabilities of IMAGINE. Using the Toolkit, an IMAGINE user can write specialized functions forhis or her particular needs. The Toolkit allows the creation of applications which are faster andmore powerful than those written with the Spatial Modeler language. In fact, the capabilities ofapplications written using the Toolkit are limited only by the C language itself and theprogrammer’s own skills. Moreover, the Toolkit enables new applications to be integrated intoIMAGINE. Examples of Toolkit applications include, but are by no means limited to, the following:

♦ Import/Export between unsupported file formats and IMAGINE files

♦ Specialized classification routines

♦ Operations on FFT images

♦ Specialized contrast algorithms

♦ Reading the ephemeris data structure from IMAGINE files created by importing from satelliteimages such as LANDSAT or SPOT

Instructions for installing the C Programmer’s Toolkit examples are given in Installing,Compiling, and Running the Example Files .

A complete list of function packages is given in Developers’ Toolkit Packages .

Reading and Writing ERDAS IMAGINE Files

If you are using the Developers’ Toolkit to read and write image files in the ERDAS IMAGINE fileformat (i.e., hardware vendors), refer to the following chapters for specific instructions pertainingto these tasks:

ERDAS IMAGINE .img Files

Hardcopy Device Drivers

Machine Independent Format

HFA Object Directory

External File Format Header Object Types

Preference Definition File

2

System Requirements

System Requirements

Before you begin using the Toolkit, you need to make sure that you have the following:

♦ The C compiler for your computer (from your computer vendor). See the table below.

♦ IMAGINE 8.4 (from ERDAS, Inc.).

♦ A good working knowledge of IMAGINE and C programming in general.

These requirements are subject to change! Check the Release Notes in the ImportantInformation Folder for corrections or visit our web site at http://www.erdas.com for the latestinformation.

Architecture Operating System C Compiler

Sun SPARCstation Solaris 2.6 SPARCompiler C 4.0

HP 9000 family,series 700 and 800

HP-UX 11 HP-UX ANSI C Developer’sBundle

IBM RS/6000 AIX 4.3.2 C for AIX 3.1.4 or C Set++ forAIX 3.1.4

DEC AlphaStation Digital Unix 4.0E A fully functional but separatelylicensed C compiler is suppliedwith the OS.

Silicon Graphics R4000and up

IRIX 6.5 ANSI C compiler shipped withIRIS Development Options 6.2

Intel Pentium Microsoft Windows NT 4.0 Visual C++ 6.0

3

Introduction to Libraries


The Developers’ Toolkit consists of a set of three libraries and about fifty include files. Thelibraries are:

♦ libelib , the core of the Toolkit,

♦ libeml , the EML (user interface) library, and

♦ libeix , which contains data import/export functions.

These libraries are located in the directory <IMAGINE_HOME>/usr/lib/arch (where arch is oneof sun4, sun4sol, decosf, sgi, hp700, rs6000 or aviion, depending on your platform). The Toolkitinclude files are located in <IMAGINE_HOME>/usr/include.

User Interface functions are found in library emllib:

The ERDAS Macro Language (EML) provides a simple means for creating and modifying aprogram interface, which is actually separate from the program. The feature which distinguishesthis from something like UIL (the Motif User Interface Language) is that in addition to thedefinition of user interface objects, EML also provides a built-in script interpreter which allowsactions as well as appearance to be customized. The eml library provides access to the ERDASMacro Language (EML) services from within a C program.

Import and Export functions are found in library eixlib:

The import/export library contains specialized functions pertaining to data import and export. Inaddition to providing functions to aid in creating new import and export programs, the librarycontains routines to read and write ephemeris data structures. Ephemeris data are the datanormally contained in the “header” of external raster data formats such as MSS, TM or SPOT.They contain information on the size and location of the image, sensor characteristics, and dateof image acquisition, among other things.

All other functions are found in library elib:

Library elib contains the majority of the functions in the Toolkit. It is grouped into packagescontaining routines with similar functionality. A complete listing of packages is given below. Allpackages begin with the letter “e” and are followed by a three-letter identifying mnemonic. Forexample, the Argument Parsing package is denoted earg.

All routines and data types in a particular package begin with the four-letter package name(earg_DoArgs, for example), and the Include file also reflects the mnemonic, such as earg.h.

Beginning Toolkit programmers should familiarize themselves first with Rules for using theDevelopers’ Toolkit and then with the following packages:

♦ eint: Toolkit Initialization

4


♦ eerr: Error Logging and Reporting

♦ earg: Argument Parsing

♦ eimg: Image File Access

5

Developers’ Toolkit Packages


Click on one of the following Toolkit Packages to go to the Index of Functions for that package.From there, you may go to the general package description (the first item in the index) or directlyto a specific function.

Occasionally you will see a reference to a macro (which looks like a function). If you click on amacro reference, you are taken to the Index of Functions. Click on the package description andlook for the definition of the referenced macro.

eant - Annotation Package

eaoi - Area of Interest Package

earg - Argument Parsing Package

ebst - Binary Search Tree Package

ecfg - Configuration manager Package

eclb - Color Library Package

ecls - Classification Package

ecvt - Unit Conversion Package

edlm - Dynamic List Manager Package

edsc - Descriptor Table Access Package

edsp - Digital Signal Processing Package

eeml - EML API Functions Package.

eerr - Error Logging and Reporting Package

eevg - Annotation Support Package.

efft - Fourier Transform Package

efga - Floating-Point Graphics Arithmetic Package

efio - Low Level File I/O Functions Package

efnp - File Node Parse Package

efsp - Feature Space Package

6


egda - General Data Arithmetic Package

ehfa - Low Level Access to the Hierarchical File Access System

ehst - Histogram and Lookup Table Package

eimg - Image File Access Package

eint - Master Toolkit Initialization Package

eirf - Image Rectification Package

eixm - Raster Import/Export Package

eklb - Kernel Library Package

ellm - Linked List Manager Package

emap - Map Printing Package

emet - Progress Meter Support Package

emif - Machine Independent Format Data Package

empu - MultiProcessor Support Package

emsc - Miscellaneous functions for common operations

emta - Magnetic Tape Access Package.

epmg - Parameter Manager Package

eprj - Map Projection Package

epxm - Pixel Management Package

erec - Rectification Package

erga - Raster GIS Analysis Package

esec - Security Package

esed - Seed (Region Growing) Package

esel - Selection Package

eshm - Shared Memory Package

esig - Signature Package

esmg - Session Manager API Package.

7


esta - Statistics Package

estr - String Package

esym - Symbol Table Management Package

etim - Timer Package.

evec - Vector Package

evue - Communication Routines for Viewer Operations

exfr - Transformation Package.

8

Rules for using the Developers’ Toolkit


Introduction

Before you begin to write C programs using the IMAGINE Developers’ Toolkit, please readcarefully the following rules. Following these rules ensures your program will be integratedclosely with the IMAGINE System’s Session Manager and will be treated just like any otherIMAGINE program.

Rules

♦ Decide what type of program you are going to develop (JOB or APPLICATION). See thedescription of these types of programs below.

♦ Never use any undocumented or private functions that you may find in the included files.Even if the undocumented/private function works for you, DO NOT use them in yourprogram. The author of these functions is free to remove them, change arguments, orchange functionality. Any change to these functions is likely to cause your program tofail.

♦ Do not install any signal handlers in your programs. This certainly will cause problems, sincethe integrity of the Session Manager depends on some specific system signals such asSIGCHLD, SIGINT, SIGHUP, SIGQUIT, SIGTSTP, SIGPIPE, SIGTERM.

♦ Do not use functions designed for a Job if your program is an Application or vice versa; doingso will produce unpredictable results.

♦ If you are not sure about a Toolkit function or the On-Line documentation is not sufficient, callToolkit Support at ERDAS for clarification. A simple call will save a lot of time at a later stageof development. Also, this will provide ERDAS with feedback on the type of problems Toolkitusers may encounter and signal us to add more documentation on these specific subjects.

Types of Programs

The Developers’ Toolkit supports two basic types of programs:

♦ GUI programs -- Programs that use a Graphical User Interface for user input. Theseprograms, after they start, will create an interface, present it to the user and wait indefinitelyfor the user input. This type of program is called an APPLICATION .

♦ Non-GUI programs -- Programs that take user input as command line arguments and startand complete the task on their own (i.e. they will not wait for user input while they arerunning). These programs also inform the user how much of the task is currently completed.This type of program is called a JOB .

9


There are different sets of functions provided under IMAGINE to build APPLICATIONS andJOBS.

1. Application - Every program which calls the function eeml_Init() is registered by theIMAGINE Session Manager as an APPLICATION. The communication between theApplication and the Session Manager is two way (i.e. the Session Manager sends/receivescommands to/from an application). An application can call all of he documented toolkitfunctions in the eeml package. Applications can freely exit with the C system call exit() anytime they need to exit. The Session Manager will automatically detect the application’s exit.

2. Job - Every program which calls the function esmg_JobInit() is registered by the IMAGINESession Manager as a JOB. The Session Manager automatically displays a progress meterfor every job. A job can regularly call esmg_JobProgress() to report the status of task to theIMAGINE Session manager which, in turn, displayed the progress in the progress meter forthat job. A job should call the esmg_InterruptQuery() function regularly during its processing.This function will inform the job whether the user has cancelled the job through the Cancelbutton provided by Session Manager in the progress meter. After it has completed, the jobmust call esmg_JobEnd() to signal the Session Manager that it is exiting. The communicationbetween a job and the Session Manager is one way most of the time (i.e., the job sendscommands to the Session Manager). For certain query commands, the Session Manager willsend a reply back to the job.

i Jobs should not call any functions designed for Applications (i.e., functions documented inthe eeml package). Conversely, Applications should not call functions designed for Jobs,such as esmg_JobInit, esmg_JobState, esmg_JobProgress, esmg_JobEnd, etc.

10

Toolkit Initialization

Toolkit Initialization

The eint package contains the function eint_InitToolkit , an initialization routine which must bethe first Toolkit function called. This function returns a pointer to a structure, Eint_InitTookitData,which is an argument in many Toolkit functions.

11

Error Logging and Reporting

Error Logging and Reporting

The eerr package provides a convenient means of reporting errors detected by Toolkit functions.Errors are reported through a structure, Eerr_ErrorReport, which contains:

♦ a pointer to subsequent Eerr_ErrorReport structures,

♦ the name of the function reporting the error

♦ a numeric code identifying the specific error within the function, and

♦ a pointer to a character string containing more information about the error.

Virtually every Toolkit function has an error argument in its calling procedure, which is the lastfixed argument of the function’s argument list. Thus, even if a Toolkit program does not use theerror reporting scheme directly, a pointer to an Eerr_ErrorReport structure must be declared toprovide an error argument to each function.

It is recommended that the error argument be checked after each Toolkit function call. If thereturned error argument is NULL, no error was detected by the function. Otherwise, the errorargument points to an Eerr_ErrorReport structure identifying the exact source of the error. Thelinked-list nature of the Eerr_ErrorReport structure allows the user to trace each function sub-calldown to the source of the error. Thus, the source of a runtime error may often be pinpointedwithout using a debugger.

12

Argument Parsing

Argument Parsing

The earg package provides a very convenient means of processing command-line argumentsand options. The package works by allowing the application developer to define an array ofEarg_Cmd structures in the application which defines the legal command-line options and thevalues which they may take. Each structure contains:

♦ a pointer to a function to execute when the argument is recognized,

♦ a description of the syntax for an option or argument,

♦ a description of the argument, and

♦ a pointer to an error function.

This structure is then passed on to the earg_DoArgs function along with the command linearguments. The parsing and error checking is done in this function. The primary function, i.e., thefunction corresponding to the name of the program itself, is always called last, and the otherfunctions are called in the order listed in the command line.

The command-line format must obey the following rules:

♦ Required arguments immediately follow the name of the program.

♦ Command-line options are indicated by a hyphen and one or more letters.

♦ Parameters belonging to an option, if any, immediately follow the option and are separatedby spaces.

For example, suppose there is a program called printtext which prints text files. The onlyrequired command line argument is the name of the file to be printed. Optionally, the line widthand page length may also be specified. The command format is

printtext filename [ -w width ] [ -l length ]

A fragment from the beginning of the program would look something like

#include <earg.h>

void ChangeWidth();void ChangeHeight();void mainfunction();

Earg_Cmd command [] = { ChangeWidth, "-w[idth] %d","Change line width",EARG_NO_ERR, ChangeHeight, "-l[ength] %d","Change page length",EARG_NO_ERR, mainfunction, "printtext %s","Main routine", EARG_NO_ERR, EARG_END

13

Argument Parsing

};

The EARG_END structure indicates the end of the array. The second element in the Earg_Cmdstructure, the format string, is similar to a printf format string. Items in brackets are optional.In the above example, the name of the program, printtext, must be followed by a string (the nameof the file), and may be followed by either -w or -l, each of which must be immediately followedby an integer. All of the following are valid invocations of the printtext program:

printtext myfileprinttext myfile -w 70printtext myfile -w 74 -l 60printtext myfile -length 60

The following are incorrect:

printtextprinttext myfile 60 74printtext myfile -w60printtext myfile -w -l 60 74

Functions governed by the Earg_cmd structure are assumed to be defined as:

voidfunctionname( argc, argv )int argc;char *argv[];

The arguments argv[1], argv[2], etc., for each function correspond to the arguments listed in theEarg_Cmd structure after the function name. For example, if printtext is called with

printtext myfile -w 70

the argument argv[1] to the function ChangeWidth is “70”. Although the format of the commanddescription may call for integers, floating point values, etc., this is for syntax error checkingpurposes only. The arguments are passed to the functions as strings in the *argv array and mustbe converted to the proper data type inside the function.

14

Coordinate Systems

Coordinate Systems

Raw Coordinate System

An IMAGINE image file is a rectangular array of pixels. The leftmost column of pixels is column0 and the topmost row of pixels is row 0. The row(y) and column (x) numbers increase to the rightand down. This is the coordinate system which is used with the eimg_LayerRead andeimg_LayerWrite functions.

Map Origin

File Origin

UpperLeft Map

LowerRight Map

CellSize X

CellSize Y

Row 0

Column 0

15

Coordinate Systems

Map Coordinate Systems

IMAGINE image files may have a cartesian map coordinate system assigned to the pixels. Thesystem has the origin at the lower left pixel in the image. The coordinate system is assigned byspecifying the map coordinate which corresponds to the center of the upperleft pixel and the mapcoordinate which corresponds to the center of the lower right pixel. The pixel separation is alsospecified as the X Cellsize and the Y Cellsize. The specification of upperleft, lowerright, andcellsize is redundant. Only the upperleft and cellsize are actually used in practice.

The following formulas are used to convert between row/column and map x/y.

The following formulas are used to convert from map x/y to row/column

Units Conversion

The map coordinates x and y and the cellsizes are in the units specified in the MapInfo object.To convert between these sizes and “meters” the ecvt package is used.

x Xul c Xsize×+=

y Yul r Ysize×–=

cx Xul–

Xsize-----------------=

ry Yul+

Ysize-----------------=

16

Coordinate Systems

The ecvt package is a generalized units conversion package, which can be used to convertdistance, angle, time, mass, etc. It is controlled by a file called <IMAGINE_HOME>/etc/units.dat.This is a simple ASCII file which contains definitions for various types of units categories suchas distance, angle, time, etc. Within each category there is a definition which consists of a unitname followed by the conversion to the standard unit.

Here is an example of the entry for distance:

distance {meters 1.0 ;meter 1.0 ;feet 0.3048006099012192 ;

:}

This says that meters (or meter) is the standard unit of distance and that feet are converted tounits by multiplying by 0.304800609901219. To add other units (surveyfeet for example) one wouldedit the units.dat file and add a new entry in the distance category which looks like “surveyfeet0.314159....; “ (whatever the proper conversion factor is). IMAGINE must be restarted for thenew units to take effect. The new units will not show up in any dialogs automatically, but they willbe understood by the system. The EML scripts must be edited to have the new unit appear tothe user.

Here is an example of reading the MapInfo header.

Eimg_MapInfo *mi;double xul, yul, xsize, ysize;double x, y;double xm, ym;int r, c;

mi = eimg_MapInfoRead(layer, NULL, &err);

if ( mi==NULL) /* No Map Information available */

xul = mi->upperLeftCenter->x;yul = mi->upperLeftCenter->y;xsize = mi->pixelSize->width;ysize = mi->pixelSize->height;/*** Get the map coordiante of pixel 100, 100.*/r = 100;c = 100;

x = xul + c*xsize;y = yul - r*ysize;

/*

17

Coordinate Systems

** x and y are in the units of the map header. To convert to meters,** do the following:*/ecvt_UnitsConvertByName(&x, mi->units.data, &xm, “meters”, 1, &err);ecvt_UnitsConvertByName(&y, mi->units.data, &ym, “meters”, 1, &err);

/*** This is somewhat inefficient because it does the lookup of “meter” and** the files units per number. Use ecvt_UnitSetByName to find the input** and output units beforehand and then just use ecvt_UnitsConvert() to do** the conversion. The x and y values can also be placed into arrays since** the unit convert functions work on arrays.*//*** The following would be used to write a simple cartesian map system to** file which is nrows by ncols.*/Eprj_MapInfo *mi;double xul, yul, xlr, ylr, xsize, ysize;

/*** Lets assume that the cellsize is 10 meters.*/xsize = 10.0;ysize = 10.0;

xul = 1000000.0;yul = 1000000.0;xlr = xul + (ncols - 1) * xsize;ylr = yul - (nrows - 1)*ysize;

mi = eprj_MapInfoCreate(&err);eprj_MapInfoUpperLeftCenterSet(mi, xul, yul, &err);eprj_MapInfoLowerRightCenterSet(mi, xlr, ylr, &err);eprj_MapInfoPixelSizeSet(mi, xsize, ysize, &err);eprj_MapInfoUnitsSet(mi, “meters”, &err);eprj_MapInfoProjectionNameSet(mi, “Unknown”, &err);/*** Now write it to the layer.*/eimg_MapInfoWrite(layer, mi, &err0;

Radial Units

If the image coordinate system is radial, i.e., it is given as latitude longitude, then the default unitsare decimal degrees (given as “dd”). A file with a projection name of “Geographic” has radialunits. The units package can be used to convert dd to radians just as it is used to convert feet tometers. However, there is nothing which forces the radial coordinate image file to be in decimaldegrees. It could be in radians as well. The programmer must check the units.

18

Coordinate Systems

Geographic Coordinates (Projections)

The MapInfo object also contains the name of the projection which is used to convert from themap system to geographic latitude / longitude coordinates. If the projection name is “Unknown”then the map system is a simple cartesian system which cannot be converted to lat/lon.However, if the name is other than “Unknown” then the map coordinates x and y can beconverted to lat/lon using the projection package.

Eprj_ProParameters *pp;Eprj_MapProjection *mapp, geop;Eprj_Point pin, pout;

if (estr_Eq(mi->proName.data, “Unknown”)... /* No Projection Info */

pp = eimg_ProParametersRead(layer, NULL, &err);

if (pp==NULL)... /* No projection info */

/*** Convert the xm, ym to lat/lon (xm,ym must be in meters. The projection package** expects all map coordinates in meters and all angle (lat/lon) in radians.*/geop = eprj_ProjectionInit(eint_GetInit(), eprj_ProParametersCreate(&err),

&err);mapp = eprj_ProjectionInit(eint_GetInit(), pp, &err);pin.x = xm;pin.y = ym;eprj_Project(&pin, mapp, &pout, geop, 1, &err);

/*** pout.x is now the longitude in radians.** pout.y is now the latitude in radians.**** ecvt can be used as above to convert to degrees.*/

Calibration

An IMAGINE image file can also have a Calibration Record. This calibration record can containa polynomial which is used to convert from r,c to x,y and vice versa. This allows an arbitrarycoordinate system to be established on the image. This transformation converts from row columnto map x and map y. The calibration has a MapInfo object which is used to assign units to thecoordinates and which is used to indicate whether there is an associated Map Projection. If thereis a map projection it is used as described above.

19

Coordinate Systems

This calibration node is accessed using the erec_CalibrationNode functions.erec_CalibrationNodeRead is used to read the calibration node. If the node is present then thisfunctions returns the rc->xy polynomial, the xy->rc polynomial, the MapInfo and theProParameters to be used with the calibration. The function efga_PolyTransCoords is used toapply the polynomial to the coordinate pairs.

NOTE: Calibrated files are discouraged at this point because the only application which dealseffectively with them is the viewer. The calibration mechanism was created so thatmeasurements could be taken directly from a file which had not been resampled. Using themeffectively in applications such as Modeler or Mosaic requires on the fly Nth order polynomialresampling, which is not yet implemented throughout IMAGINE.

20

Image File Access

Image File Access

The eimg package is used to access raster data from disk files. Because data in IMAGINE filesis stored in a flexible, hierarchical, tree-structured format, it is essential that the Toolkit be usedfor file access. Using eimg, the individual pixels in an image may be accessed, as well as mapand projection information, image statistics, histogram data, color tables, and other descriptortables.

Raster data is stored in layers, which are two-dimensional arrays of data where each element ofthe array corresponds to a data file value. For example, a true color RGB image contains threelayers, one for each band. Each layer in a file has a unique name which is used to access it. Thevarious layer names in a file may be found using the eimg_LayerGetNames function. Individuallayers may be opened in much the same way as files: they may be opened as read-only, etc. Inorder to manipulate raster data, the Eimg_PixelRect structure is used. This is a buffer into whicha layer or rectangular subset of a layer may be read. Using an Eimg_PixelRect, data may bemanipulated at the pixel level, or arithmetic functions may be applied to the entire area.

The discussion of ERDAS IMAGINE .img Files explains how to import and export image files inthe IMAGINE format.

21



ERDAS IMAGINE uses .img files to store raster data. These files use the ERDAS IMAGINEHierarchal File Format (HFA) structure. Figure 1, below, shows the different objects of datastored in a .img file. The contents of the .img file is not fixed. Many of the items shown below areoptional. In addition, because of the open nature of the file format, other developers may createand add new types of items to the file.

The Developers’ Toolkit provides programmers with the functions needed to read and writeERDAS IMAGINE .img files. Even though the file format is documented in the HFA ObjectDirectory chapter, it is recommended that you read this section because it will greatly reducedevelopment time. In addition, it will guarantee compatibility with future versions of the .img fileformat.

Figure 1: Examples of Objects Stored in a .img File

File Information

Each .img file stores basic information about the file, including:

♦ file name

♦ layer name

.img file

FileInfo.

GroundControlPoints

SensorInfo.

Layer_1 Layer_2 Layer_n

LayerInfo.

Attribute Data

Statistics MapInfo.

ProjectionInfo.

PyramidLayers

DataFileValues

compression block size

22


♦ number of layers

♦ date the file was last modified

This information applies to all of the layers.

Sensor Information

When you import satellite imagery from a tape or CD-ROM, there is usually a header filepreceding the image data on the input medium which is extracted by the import program andstored as an object in the .img file. This object contains ephemeris information about the sensor,such as:

♦ date and time scene was scanned

♦ calibration information of the sensor

♦ orientation of the sensor

♦ original dimensions for data

♦ data storage format

♦ number of bands

The data presented are dependent upon the sensor. Each sensor provides different types ofinformation. The sensor object is named:

<format type>_Header

Sensor Sensor Object

ADRG ADRG_Header

ADRI ADRI_Header

DEM DEM_Header

DTED DTED_Header

Landsat TM TM_Header

Landsat MSS MSS_Header

NOAA AVHRR AVHRR_Header

SPOT SPOT_Header

23


Raster Layer Information

Each raster layer within a .img file has its own ancillary data, including the following parameters:

♦ height and width (rows and columns)

♦ layer type (continuous or thematic)

♦ data type (signed 8-bit, floating point, etc.)

♦ compression (see below)

♦ block size (see below)

This information is usually the same for each layer.

Compression

When you import a file into ERDAS IMAGINE you have the option to compress the data.Currently, ERDAS IMAGINE uses the run-length compression method. The amount that the dataare compressed depends on data in the layer. For example, if the layer contains largehomogenous areas (e.g., blocks of water) then compressing the layer would save you diskspace. However, if the layer is very heterogenous, then run-length compression would not saveyou much disk space.

Data will be compressed only when it is stored. ERDAS IMAGINE automatically uncompressesdata before the layer is run through a process. The time that it takes to uncompress the data isminimal.

Block Size

ERDAS IMAGINE software uses a tiled format to store raster layers. The tiled format allows rasterlayers to be displayed and resampled quickly. The raster layer is divided into tiles (i.e., blocks)when ERDAS IMAGINE creates or imports a .img file. You can define the size of these blockswhen you either create the file or import it. The default block size is 64 pixels by 64 pixels.

i The default block size is acceptable for most applications and should not need to be changed.

24


Figure 2: Example of a 512 x 512 Layer with a Block Size of 64 x 64 Pixels

64

64

512

512

columns

rows

pixels

pixels

25


Attribute Data

Continuous Raster Layer

The attribute table object for a continuous raster layer, by default, includes the followinginformation:

♦ histogram

♦ contrast table

Thematic Raster Layer

For a thematic raster layer, the attribute table object, by default, includes the followinginformation:

♦ histogram

♦ class names

♦ class values

♦ color table (red, green, and blue values).

Attribute data can also include additional information for thematic raster layers, such as the area,opacity, and attributes for each class.

Statistics

The following statistics are calculated for each raster layer:

♦ minimum and maximum data file values

♦ mean of the data file values

♦ median of the data file values

♦ mode of the data file values

♦ standard deviation of the data file values

You should create statistics for a layer if they do not exist. Certain Viewer functions (e.g., contrasttools) will not run without layer statistics. Rebuilding statistics for a raster layer may benecessary. For example, if you decide that you do not want to include zero file values in thestatistics calculation (and they are currently included), you could rebuild the statistics withoutzero file values.

26


Map Information

Map information for a raster layer will be created only when the layer has been georeferenced.If the layer has been georeferenced, the following information will be stored in the raster layer:

♦ upper left X,Y coordinates

♦ pixel size

♦ map unit used for measurement (e.g., meters, inches, feet)

Map Projection Information

If the raster layer has been georeferenced, then the following projection information will begenerated for the layer:

♦ map projection

♦ spheroid

♦ zone number

Pyramid Layers

ERDAS IMAGINE gives you the option to “pyramid” large raster layers for faster processing anddisplay in the Viewer. When you generate pyramid layers, reduced, subsampled raster layers arecreated from the original raster layer. The number of pyramid layers that are created depends onthe size of the raster layer and the block size.

For example, a raster layer which is 4k x 4k pixels could take a long time to display when usingthe Viewer Fit To Window option.Using the Compute Pyramid Layers option in ImageInfo willcause ERDAS IMAGINE to create additional raster layers successively reduced from 4k x 4k, to2k x 2k, 1k x 1k, 512 x 512, 128 x 128, down to 64 x 64. Then ERDAS IMAGINE would selectthe pyramid layer size most appropriate for display in your Viewer window.

Reading and Writing .img Files

This section describes each of the C Toolkit packages that are needed to read and write ERDASIMAGINE .img files. The detailed format of the .img file is documented in Machine IndependentFormat and HFA Object Directory .

ERDAS IMAGINE functions are grouped into packages named with four letter mnemonics thatalways begin with a lowercase e. Each package focuses on some specific area of functionality.The complete reference pages for each package are accessible from Developers’ ToolkitPackages .

27


Each package has an associated header file whose name is constructed from the package nameplus the .h extension. All of the data types and function prototypes for the package are definedin the header file. Most packages create one or more types of structures. There are functionsprovided in each package to free the specific data type. The name is either exxx_DataTypeFreeor exxx_DataTypeDelete.

This section gives an overview of each package. Click on the package name to open thereference pages for that package.

eerr

The eerr package is the ERDAS IMAGINE error handling system. Most functions take a pointerto an Eerr_ErrorReport *. The Eerr_ErrorReport is a structure which contains an error code andan error message. If a NON-NULL value is returned for this argument then an error has occurred.The code can be checked and the message can printed. Whether or not the error report isprinted, it is the caller’s responsibility to free it.

emif

The lowest level of the I/O packages is the emif (ERDAS Machine Independent Format)package. Emif provides tools for creating definitions of C structures so that they can be writtento a file on one machine and read back on another with a different architecture.

The emif package works with designs which reside in dictionaries. Each design is a descriptionof a C structure. The design tells the emif package how to pack and unpack the data betweenthe computers host memory and the storage medium. Each design is created and placed in adictionary. The dictionary can be written out in a compact form.

The details of the emif disk file format and dictionary format are given in the MachineIndependent Format chapter.

ehfa

The ehfa (ERDAS Hierarchal File Architecture) package is built on top of the emif package. Itprovides the tools to create a tree structured collection of objects in a single file which can bewritten and read as named objects.

Every node in an HFA file has a name. The full HFA node path name is formed by enumeratinga colon separated list of all direct ancestors of that node starting from the root node. For examplelanier.img(:Layer_1:Descriptor_Table:Histogram) is the name of the table which contains thehistogram information for Layer_1 in the file lanier.img.

A directory of the objects stored in an IMAGINE .img file are given in the HFA Object Directorychapter.

28


edsc

The edsc package is used to create and maintain descriptor tables. A descriptor table is a nodein the file which contains one or more columns of information. The main descriptor table in a .imgfile is used to store information which is specific to each pixel value, such as histograms orcontrast tables. At other times, they are simply used to store a variable list of objects that havecommon attributes such as ground control points.

Each column in a descriptor table can be though of as an array of integers, floats, or strings. Allcolumns in a given table must have the same number of elements.

eprj

The eprj package provides the functions used to create, manipulate, and maintain map andprojection information. The map information describes the map origin and cell size for the pixelsin an image which are used to convert from pixel row column to map x, y. The projectioninformation is used to convert from map x,y to latitude, longitude.

The HFA Object Directory chapter contains a description of the information found in theprojection record in the file.

esta

The esta package provides the functions used to create, manipulate, and maintain imagestatistics. These include single layer statistics such as mean, maximum, minimum, standarddeviation, and multilayer statistics such as the covariance matrix.

eimg

The eimg package is the main interface to ERDAS IMAGINE .img files. It is built upon thepreviously described packages and, for the most common operations of reading and writingimage data, it provides the complete interface to the ERDAS IMAGINE .img files.

estr

The estr (string) package provides a number of functions for manipulating strings of charactersand arrays of strings of characters.

emap

The emap package contains functions for reading and writing map composition files.

29



Introduction

The IMAGINE Developers’ Toolkit can be utilized by a hardware distributor to develop a devicedriver that will read image files in ERDAS IMAGINE format and output the raster data to one ofthe distributor’s hardcopy output devices. This chapter discusses the elements of the mapcreation process in ERDAS IMAGINE that are relevant to the development of a device driver ofthis sort.

To fully integrate a distributor’s hardware with ERDAS IMAGINE software, the following fouritems must be provided by the distributor to those clients who wish to use the distributor’shardware from within ERDAS IMAGINE:

♦ a Preference Definition File - describes the hardware parameters

♦ a device setup file - incorporates the printer into the print job spooling system

♦ a raster filter - converts data from ERDAS IMAGINE format

♦ an installation script - places the files above in the appropriate directories

This documentation includes instructions for creating these four files.

Roles of Map Composer, Mapmaker, and Printmanager

Map Composer is a program within ERDAS IMAGINE that enables users to create maps. Mapsare created graphically on the screen but the actual file created (.map extension) is an HFA filecontaining a description of the map.

Mapmaker is a program within ERDAS IMAGINE that transforms a map composition from amulti-file form where each file represents all of the graphics for a specific element or set ofelements of a map, to a different multi-file form where each file represents all of the graphics fora specific area of the map.

Printmanager is a program within ERDAS IMAGINE that delivers panel files created byMapmaker to a printer.

Running Map Composer, Mapmaker, and Printmanager

The Mapmaker program is invoked when you select the Print Map Composition option fromMap Composer.

During execution, Mapmaker creates the following files:

♦ one or more panel files - containing bitmapped data for the map

30


♦ one or more name files - each containing the full path name of a panel file

♦ one plot file - containing the list of name files

♦ one configuration file - containing replacement values for hardware parameters specified atthe time of printing

The following table shows the file naming convention:

Mapmaker handles all of the rendering details including conversion of graphics (lines, polygons,text, etc.) into a raster form. It also handles the use of halftoning to approximate continuous toneson a binary device.

Mapmaker reads the map file created by Map Composer, and renders it into one or more panelsaccording to a Preference Definition File (PDF). A panel is a generic term for a section of the mapthat will fit onto a single piece of paper. The PDF defines, among other things, the paper sizeavailable in the selected printer.

The output product from the example .map file above contains a grayscale image, a vector datalayer, and an annotation layer. The basic structure is depicted in Figure 1 .

File Type File Name Structure

map file filename.map

plot file filename.plt

configuration file printers.filename.plt.cfg

panel file filename.plt.panel_#

name file filename.plt.panel_#.name

PDF printername.pdf

raster filter vf_printername

device setup script printer_printername

31


Figure 1: Example Plot Layout

Mapmaker reads the PDF file which describes the characteristics of the selected printer. (SeePreference Definition File for details.) Mapmaker uses these characteristics to determine thenumber of panels it needs to fully cover the map composition, the panel file data type (1-bit, or8-bit), and the halftone details (if it renders to 1-bit). It also passes all of the PDF values that weremodified at the time of printing to the configuration file, printers.filename.plt.cfg, that is associatedwith the plot.

7.5 inches

5.0 inches

1.3 in

ATLANTIS

plot origin

map origin

map clip

5.0 inches

3.0 inches

10.0 inches

32


The panel file into which it renders is named filename.plt. panel_#. The # in the panel file namedenotes the panel number. Panel numbers begin with 0. Panels are numbered from left to rightand top to bottom. A six panel map would be arranged as shown in Figure 2 .

Figure 2: Panel Arrangement

Each individual panel file is no different from a .img file (the file format used to store raster datain ERDAS IMAGINE).

Mapmaker also creates a name file which records the full path and name of all files associatedwith a panel file. This is especially useful for devices such as Postscript printers, where fonts canbe downloaded to the printer separately. The naming convention for the name file isfilename.plt.panel_#.name. If the correct argument is specified, Mapmaker will invokePrintmanager when each panel is complete.

After Mapmaker finishes all of the panels, it makes a plot file, filename.plt, which contains all ofthe paths of the name files it has generated. This file allows the user to print selected panels ata later time via the Plotfile program by using the Print Plot File option in the Map Composerdialog box.

Figure 3 below, and Figure 4 show how these pieces of software fit together.

0 1

2 3

4 5

33


Figure 3: The ERDAS IMAGINE Map Composer and Mapmaker processes

configuration file

Mapmaker

plot file

name file

panel file

MapComposer

map file

IMAGINE filesassociated

with map file

PDF

34


Figure 4: Relationship of Vendor Software and Hardware to the ERDAS IMAGINE Plotfileand Printmanager processes

plot file

Plotfile

rasterfilter

printer jobspoolingsystem

Printmanager

Networkprinter

fileconvertedpanel data file

control data

printer jobspoolingsystem

System Queuewith IMAGINE JetDirect or

Calcomp981SystemQueuePrint Accelerator

printer

fileconvertedpanel data

printer

Mapmaker

configuration file,panel file,name file

configuration file,panel file,name file

35


The Preference Definition File

Device driver developers must define a Preference Definition File which describes theparameters of the I/O device which they wish to drive.

In conjunction with special facilities in ERDAS IMAGINE, the Preference Definition File (PDF)provides the user with a graphical way of modifying the values of parameters used to outputmaps to the hardware associated with the PDF. The PDF is read by ERDAS IMAGINE’sConfiguration Manager which uses the information to allow the Configuration Editor to generatea graphical display similar to the one in Figure 5 .

Some of the parameters specified in a PDF are used by Mapmaker. These parameters havefixed names which must be used if Mapmaker is to identify the appropriate parameter values forthe parameters it seeks. For example, media size, number of colors, number of copies, and dotdensity are all determined by Mapmaker by seeking from the Configuration Manager the valuesof certain reserved preference names.

Other parameters of the PDF are used by the Configuration Editor to tie the printer into theworkstation’s printer job spooling system. These parameters, like the ones used by Mapmaker,have reserved names.

Parameters other than these two types may be specified in a PDF. These additional parameterswould be specific to the hardware associated with the PDF and they would by placed in a PDFso the raster filter created to drive the hardware could access their configured values at the timeof printing.

The PDF should have the name printername .pdf where printername is a name similar tothe name of the hardware that the PDF governs.

The complete syntax of the PDF is described below. In brief, the PDF syntax supports thedefinition of the following types of parameters:

♦ character stringExample:

model (“Printer Model”) : “Kodak XL7700” “Printer manufacture and model”;

♦ enumeratedExample:

color (“Color Options”): “RGB” “Printer color paths”enums{“RGB” “Red green Blue”“Black” “Black Only”};

♦ numericExample:

36


numcopies (“Number of Copies”) : 1“Number of copies to print”min 1max 1000;

♦ booleanExample:

mirror (“Use a Mirrored Image”) : “false” “Is the image mirrored?”boolean “true” “false”;

The Preference Definition File syntax is described by the following BNF. A complete example isgiven in a Preference Definition File Example.

<PDF File> -> <PD> <PD List><PD List> -> <PD> <PD List> | NULL<PD> -> : ; -> NAME -> ( STRING ) | NULL -> <Boolean Dflt> | <String Dflt> | <Number Dflt> | <Enum Dflt><Boolean Dflt> -> <True Dflt> | <False Dflt><True Dflt> -> “yes” | “on” | “true”<False Dflt> -> STRING<String Dflt> -> expand STRING | STRING<Number Dflt> -> NUMBER<Enum Dflt> -> STRING -> STRING -> <Boolean Info> | <String Info> | <Number Info> | <Enum Info><Boolean Info> -> boolean STRING STRING<String Info> -> maxlength NUMBER | NULL<Number Info> -> <Number Min> <Number Max><Number Min> -> min NUMBER | NULL<Number Max> -> max NUMBER | NULL<Enum Info> -> ENUMS { <Enum> <Enum Data> }<Enum Data> -> <Enum> <Enum Data> | NULL<Enum> -> <Enum Choice> <Enum Help><Enum Choice> -> STRING<Enum Help> -> STRING

If we use regular expression syntax of the type used by ‘egrep’, we can define the terminalsymbols as follows:

NAME[a-zA-Z] [a-zA-Z0-9_]*

(i.e., any sequence of alphanumeric characters beginning with an alphabetic character. NAME’sare not case sensitive so Name, NAME and name will all be recognized as the same NAME.)

STRING“([^”]*(\\”)?)*”

(i.e., any sequence of characters between double quotes. Quoted double quotes should beprotected by backslashes)

NUMBER-?([0-9]*\.?[0-9]+|[0-9]+\.?[0-9]*)([Ee]([-\+])?[0-9]+)?NULLis null

37


Once a parameter has been defined in the PDF, the value of that parameter can be modified toa preferred value by the user through the ERDAS IMAGINE Configuration Editor. For this reason,the parameters described by a PDF are referred to as ‘preferences’.

The dialog box that is automatically generated by ERDAS IMAGINE’s Configuration Editor forthe example PDF is shown in Figure 5 , below. The numbered key can be used to match a portionof the PDF syntax with its corresponding graphical display.

Figure 5: Preference Dialog Example

1 3

2

4

6

5

38


 The preference title allows the user to identify the valuesthat he would like to modify during printer configuration. Inthis example, the preference title of the ‘model’ preference(“Printer Model”) is reflected in the graphical display.

<Number Dflt> Numeric preferences are displayed in an editable‘textnumber’ field. The user can change this value bytyping or by clicking the small nudgers on the right side ofthe field. In this example, the default value of the ‘media-width’ preference is reflected as ‘8.5000’ in the graphicaldisplay.

<String Dflt> String preferences are displayed in an editable text field.The user can change the value by typing in this field. In thisexample, the default value for the ‘model’ preference(“Kodak XL7700”) is reflected in the graphical display.

<Enum Dflt> Enumerated preferences are displayed as a popup list ofthe enumerated choices. The user can change the valueby selecting a different option from the popup list. Thedefault value of the ‘unittype’ preference (“BSD”) iscurrently selected in this example.

<Boolean Dflt> Boolean preferences are displayed as a shaded box. The“true,” “yes,” or “on” state is indicated by a black box thatappears depressed. The false value is indicated by a graybox that appears raised. The user can change the value byclicking on the box. In this example, the value for the‘mirror’ preference is set to false, the default setting.

{:<Enum Help>} The help string(s) provided in a preference definition isdisplayed in the single line help status bar of the Configu-ration Editor dialog box as the user moves the mouse overthe preference titles. The enumerated help string corre-sponding to the currently selected enumerated choice isconcatenated to the main help string in the case ofenumerated preferences.

The table below shows a complete list of the preference names reserved by ERDAS IMAGINE.This table also indicates which preferences MUST be present in any new PDF created to supportan output device (footnote a).

preferencename Preference Title Example Value

acceleratora Use Imagine Print Accelerator “yes”

1

2

3

4

5

6

39


additivecolor Use Positive Paper "True"

autofont Send fonts to printer instead of plot file? "False"

colora Color Options "RGB" b

connectiona Printer Connection “System Queue”

densitya Transparent Density “Normal”

densitywidtha Horizontal Dot Density 203c

densityheighta Vertical Dot Density 203d

devicea Local Device “/dev/bpp0”

directoryname Output Directory $HOME

dotsunittypea Dot Units "inch"

filename Output File “<template>.out”

imaginenamea Imagine Print Queue Name “xl7700”

intenselevela Color Intensity Level 256

mediawidth Media Width 8.5

mediaheight Media Height 11

mirror Use a Mirrored Image "False"

model Printer Model "Kodak XL7700"

numcopiesa Number of Copies 1

othercommand Other Command “lpr”

plotpath ServeWare Plot Directory “/usr/plots/imagine_plots”

postscriptlevel PostScript Level 1

postscriptversion PostScript Version 52.3

queuehosta Printer Host Name $HOSTNAMEd

queuetypea Queue Type “BSD”

screenangle_black Black Screen Angle 45

screenangle_cyan Cyan Screen Angle 15

screenangle_magenta Magenta Screen Angle 75

screenangle_yellow Yellow Screen Angle 0

40


a. This preference MUST be present in any new PDF created to support an output device.b. Colors are limited to red(R), green(G), blue(B), cyan(C), magenta(M), yellow(Y), and black(K) andcertain combinations of 2 to 4 of these colors.You may use the color name with an initial capital letter orsimply the capital letter designated beside the color name above.c. Zero (0) in this field indicates no limit.d. This name is expanded to be the name of the host on which you are configuring the printer.e. Units of measure may be anything that is defined in <IMAGINE_HOME>/etc/units.dat.

The Device Setup Script

The function of the device setup script is to incorporate a printer that a user has defined inERDAS IMAGINE into the print job spooling system of the workstation. An overview of the printerconfiguration process in ERDAS IMAGINE will make the necessary contents of the device setupscript more understandable.

Before a printer can be configured in ERDAS IMAGINE and used to print maps, the printershould be physically connected to a workstation or network and tested to ensure that data canbe successfully sent to the device. The instructions for doing this are usually provided by thehardware vendor.

To enable access to the printer from within ERDAS IMAGINE the user must:

♦ Use the ERDAS IMAGINE Configuration Editor to create a new printer device

♦ Set the preferences of the newly created device to the desired values

♦ Create a print queue for the new printer device on every workstation from which the userwishes to access the printer

To create a printer device, the user chooses a template of preferences for the device and givesthe device a name. The name of the device is the name that will be used throughout ERDASIMAGINE to refer to this printer configuration. The template of preferences is one of the PDF filesthat apply to printers. PDF files distributed by hardware vendors may be among the templatesfrom which the user can choose.

screenfrequency Halftone Screen Frequency 60

totalpixelheighta Total Vertical Pixels 1536

totalpixelwidtha Total Horizontal Pixels 2048

unittype Media Units "inch" e

41


As mentioned in the previous section, there are several preferences that pertain to printer devicesetup that must exist in each PDF that applies to a printer device. These preferences must beset by the user to appropriate values after the printer device is created in ERDAS IMAGINE andbefore the user attempts to create a print queue for the new printer. These preferences and theirmeanings are:

imaginename - The ERDAS IMAGINE Configuration Editor allows any manner of name to beused for the printer device. For instance, the user could call a printer device “LaserJet by Bob’sdesk.” UNIX print queue names, on the other hand, are usually restricted in the form that theycan take. In addition, for some devices that have their own internal queueing mechanism, thequeue name must be fixed. The value of this preference will be used to construct the name ofthe UNIX queue for the printer.

connection - The ERDAS IMAGINE Printmanager now supports several connection types,including local and remote system queues, network printers, and files. For third party devicedrivers, this option should always be set to “System Queue” so that the external printer driver isused.

accelerator - This preference controls the delivery method used with printers connected tosystem queues. When it is off, the Printmanager spools the translated file. When it is on, thetranslating filter is run by the system queue and the Printmanager spools a small control file. Forthird party device drivers, this option should always be set to “Yes” so that the external printerdriver is used.

queuehost - This preference should be set to the host on which the ‘local’ print queue for theprinter resides. This is usually the machine to which the printer is actually attached.

device - This preference should be set to the name of the device file through which the printermay be accessed. For printers that attach directly to the network, this preference is usuallydefined in the PDF with a default value of /dev/null.

After setting the parameters appropriately, the user will attempt to create a print queue throughthe Configuration Editor. The Configuration Editor passes the printer name and the threepreference values mentioned above, along with the name of the template on which theparameter definitions for this printer were based (the PDF file name) to a shell script called‘install_printer’ . This shell script produces another shell script that, when executed asthe root user, will change the system files on the user’s workstation so that an appropriate printqueue is created for this printer. This two stage process allows system administrators to examinethe commands which will be run by IMAGINE, before executing scripts that change systemconfiguration files.

42


The actual name of the queue created for the printer will depend on the queuehost, acceleratorand imaginename preferences, along with the version of IMAGINE. If the printer is on a remotehost, the first 3 letters from the queuehost value will be used as a prefix for the UNIX queuename. If the accelerator preference value is ‘Yes” (as it should be for all 3rd party drivers), theversion of IMAGINE will be appended to the end of the UNIX queue name. So creating a queueon host oak to point to a printer named lp served on host spruce would result in a queuenamed sprlp . If this queue uses the accelerator, the queue would be named sprlp830(assuming the user is using IMAGINE version 8.3).

In order to be able to create a script that will modify the system configuration files appropriatelyfor this particular printer, the install_printer script calls on a function namedprinter_create_ printername where printername is the template name (PDF file name)passed to the install_printer script. This function may be defined externally because theinstall_printer script will source any file that it finds that is calledprinter_ printername .

Therefore, the device setup script that a hardware vendor must deliver with the PDF file andraster filter is a script called printer_ printername . The script must contain at least onefunction definition, printer_create_ printername , which defines a function capable ofgenerating script commands that will add the printer to the printer control files of the host platform(e.g., /etc/printcap on the SUN).

If the script cannot serve all architectures on which the printer is intended to be supported,override scripts must be provided for each supported architecture. These scripts must be namedo_printer_ printername _arch where arch is one of the architecture names recognized byERDAS IMAGINE.

The install_printer script is distributed with the IMAGINE Developers’ Toolkit. It containsmany examples of printer_create_ printername function definitions representing the‘printer devices’ supported for ERDAS IMAGINE by ERDAS.

ARCH Name Company Name

decosf Digital Equipment Corp.

hp700 Hewlett-Packard Co.

rs6000 International Business Machines Corp.

sgi Silicon Graphics, Inc.

sun4 Sun Microsystems, Inc. (Sunos 4.1.4)

sun4sol Sun Microsystems, Inc. (Solaris2.5)

43


The Raster Filter

The raster filter is the actual device driver which can convert a .img formatted panel file to theformat expected by the printer. This executable must be designed as a UNIX filter, i.e., it mustread from the standard input and write to the standard output. The filter must be namedvf_ printername .

Inside the Printmanager program of ERDAS IMAGINE, a control file is queued to the UNIXsystem queue. The control file will contain the specific control information listed below, with eachitem on a separate line.

Therefore, in normal operating mode, the standard input for raster filter will receive controlinformation similar to the example below from the printer job spooling system.

0yourfilter001files/full/path/to/panel/file/on/nfs/mounted/drive/filename.plt.panel_#

The example C program, fxhardcopy.c, demonstrates one way to read raster data into a rasterfilter. Use the following command to output an ASCII representation of a 20X20 data value areaof band 2 of the input image starting at row 30, column 40. This output may also be piped to moreor redirected to an ASCII file. The file size will be about 108 Kilobytes.

% runex fxhardcopy -in -x40 -y 30 -w 20 -h 20 -f 2 -t 2 <IMAGINE_HOME>/examples/hardcopy_data.img

Control Parameter Value Range

verbose flag 0 or 1

filter name Name of output filter to be used

xoffset integer

yoffset integer

number of copies integer

data source “files”

filenames list of panel data file names, one per line

44


The program also shows how the preference values of preferences associated with the outputdevice might be obtained. To enable the portion of code that obtains preference values, performthe following steps after the sample programs have been built (directoryname represents thefull directory path into which the Developers’ Toolkit was installed, including the imagine830tkpostfix):

% cd directoryname

% ln -s <IMAGINE_HOME>/examples/hardcopy_data.img hardcopy.plt.panel_0

% runex fxhardcopy -in -w0 -h0 directoryname /hardcopy.plt.panel_0

These steps simulate the environment within which a raster filter runs. Theprinters.hardcopy.plt.cfg file may be altered to simulate changes to the preference values duringsubsequent print jobs. Any preference values that are not mentioned in theprinters.hardcopy.plt.cfg file have their default values taken from the <IMAGINE_HOME>/devices/printers/kodak.pdf file.

Certain configuration information may also be obtained via the plotfileheader. This method ofobtaining configuration information is becoming obsolete, however, and should be avoidedwhere possible.

The Installation Script

An installation script is recommended. The installation script should copy the following files asshown:

♦ the raster filter vf_ printername compiled for each architecture to be supported should beplace in the <IMAGINE_HOME>/bin/<ARCH > directory

♦ the PDF printername .pdf should be placed in the <IMAGINE_HOME>/devices/printers directory

♦ the device setup script printer_ printername and any override scripts namedo_printer_ printername _<ARCH> should be place in the <IMAGINE_HOME>/bindirectory and should be accessible through symbolic links from the <IMAGINE_HOME>/install directory.

User Installation

After a hardware vendor installation script has been run, an IMAGINE user must:

♦ Start ERDAS IMAGINE

♦ Configure the printer using the Configuration Editor

45


♦ Create a print queue creation script using the Configuration Editor and the print queuecreation script generated by the install_printer script.

The newly configured printer will then be accessible from the various Map Composition dialogboxes and the user will be able to print maps to the printer.

➲ Instructions for the user may be modeled after the example printer configuration instructionsin the ERDAS IMAGINE Installation Guide .

46



MIF Data Elements

ERDAS IMAGINE uses the Machine Independent Format (MIF) to store data in a fashion whichcan be read by a variety of machines. This format provides support for converting data betweenthe IMAGINE standard data format and that of the specific host's architecture. Files createdusing this package on one machine will be readable from another machine with no explicit datatranslation.

Each MIF file is made up of one or more of the data elements explained below.

EMIF_T_U1 (Unsigned 1-bit Integer)

U1 is for unsigned 1-bit integers (0 - 1). This data type can be used for bitmap images with “yes/no” conditions. When the data are read from a MIF file, they are automatically expanded to giveone value per byte in memory. When they are written to the file, they are automaticallycompressed to place eight values into one output byte.


U2 is for unsigned 2-bit integers (0 - 3). This data type can be used for thematic data with 4 orfewer classes. When the data are read from a MIF file they are automatically expanded to giveone value per byte in memory. When they are written to the file, they are automaticallycompressed to place four values into one output byte.

7

U1_7

6

U1_6

5

U1_5

4

U1_4

3

U1_3

2

U1_2

1

U1_1

0

U1_0

byte 0 (8 bits)

7

U1_7

5

U2_2

3

U2_1

1

U0_0

byte 0 (8 bits)

6 4 2 0

47



U4 is for unsigned 4-bit integers (0 - 15). This data type can be used for thematic data with 16 orfewer classes. When these data are read from a MIF file, they are automatically expanded to giveone value per byte. When they are written to the file they are automatically compressed to placetwo values into one output byte.

EMIF_T_UCHAR (8-bit Unsigned Integer)

This stores an 8-bit unsigned integer. It is most typically used to store characters and rasterimagery

EMIF_T_CHAR (8-bit Signed Integer)

This stores an 8-bit signed integer.

EMIF_T_USHORT (16-bit Unsigned Integer)

This stores a 16-bit unsigned integer, stored in Intel byte order. The least significant byte (byte0) is stored first.

7

U4_1

3

U4_0

byte 0 (8 bits)

04

7

integer

byte 0

0

7

integer

byte 0

0

48


EMIF_T_SHORT (16-bit Signed Integer)

This stores a 16-bit two’s-complement integer, stored in Intel byte order. The least significantbyte is stored first.

EMIF_T_ENUM (Enumerated Data Types)

This stores an enumerated data type as a 16-bit unsigned integer, stored in Intel byte order. Theleast significant byte is stored first. The list of strings associated with the type are defined in thedata dictionary which is defined below. The first item in the list is indicated by 0.

EMIF_T_ULONG (32-bit Unsigned Integer)

This stores a 32-bit unsigned integer, stored in Intel byte order. The least significant byte isstored first.

15

integer (16 bits)

byte 1 byte 0

0

15

integer (16 bits)

byte 1 byte 0

0

15

integer (16 bits)

byte 1 byte 0

0

49


EMIF_T_LONG (32-bit Signed Integer)

This stores a 32-bit two’s-complement integer value, stored in Intel byte order. The leastsignificant byte is stored first.

EMIF_T_PTR (32-bit Unsigned Integer)

This stores a 32-bit unsigned integer, which is used to provide a byte address within the file. Byte0 is the first byte, byte 1 is the second, etc. This allows for indexing into a 4-Gigabyte file,however most UNIX systems only allow 2-Gigabyte files.

i Currently, this element appears in the data dictionary as a EMIF_T_ULONG element. Infuture versions of the file format, the EMIF_T_PTR will be expanded to an 8-byte formatwhich will allow indexing using 64 bits which allow addressing of 16 billion Gigabytes of filespace.

31

integer (32 bit)

byte 3 byte 2 byte 1 byte 0

0

31

integer (32 bit)


0

31

integer (32 bit)


0

50


EMIF_T_TIME (32-bit Unsigned Integer)

This stores a 32-bit unsigned integer, which represents the number of seconds since 00:00:00 1JAN 1970. This is the standard used in UNIX time keeping. The least significant byte is storedfirst.

EMIF_T_FLOAT (Single Precision Floating Point)

Single precision floating point values are IEEE floating point values.

s = sign (0 = positive, 1 = negative)exp= 8 bit excess 127 exponentfraction = 24 bits of precision (includes 1 implied bit)

EMIF_T_DOUBLE (Double Precision Floating Point)

Double precision floating point data are IEEE double precision.


31

integer (32 bit)


0

22

fraction


30

exp

31

s

023

51

fraction


62

exp

63

s


52 0

51


EMIF_T_COMPLEX (Single Precision Complex)

A complex data element has a real part and an imaginary part. Single precision floating pointvalues are IEEE floating point values.


Real part: first single precision

Imaginary part: second single precision

EMIF_T_DCOMPLEX (Double Precision Complex)

A complex data element has a real part and an imaginary part. Double precision floating pointdata are IEEE double precision.


Real part: first double precision

22

fraction


30

exp

31

s

023

22

fraction


30

exp

31

s

023

52


Imaginary part: second double precision

EMIF_T_BASEDATA (Matrix of Numbers)

A BASEDATA is a generic two dimensional array of values. It can store any of the types of dataused by IMAGINE. It is a variable length object whose size is determined by the data type, thenumber of rows, and the number of columns.

numrows: This indicates the number of rows of data in this item.

numcolumns: This indicates the number of columns of data in this item.

51

fraction


62

exp

63

s


52 0

51

fraction


62

exp

63

s


52 0

31

integer (32 bit)


0

31

integer (32 bit)


0

53


datatype: This indicates the type of data stored here. The types are:

objecttype: This indicates the object type of the data. This is used in the IMAGINE SpatialModeler. The valid values are:

Data Type BytesPerObject

0 EMIT_T_U1 1/8

1 EMIF_T_U2 1/4

3 EMIT_T_U4 1/2

4 EMIF_T_UCHAR 1

5 EMIF_T_CHAR 1

6 EMIF_T_USHORT 2

7 EMIF_T_SHORT 2

8 EMIF_T_ULONG 4

9 EMIF_T_LONG 4

10 EMIF_T_FLOAT 4

11 EMIF_T_DOUBLE 8

12 EMIF_T_COMPLEX 8

13 EMIF_T_DCOMPLEX 16

0 SCALAR. This will not normally be the case, since ascalar has a single value.

1 TABLE: This indicates that the object is an array. Thenumcolumns should be 1.

2 MATRIX: This indicates the number of rows and columnsis greater than one. This is used for Coefficient matrices,etc.

15

integer (16 bits)

byte 9 byte 8

0

54


data: This is the actual data. The number of bytes is given as:

bytecount = numrows x numcolumns x BytesPerObject

EMIF_M_INDIRECT (Indication of Indirect Data)

This is used when the following data belongs to an indirect reference of data. For example, whenone object is defined by referring to another object.

The first four bytes provide the object repeat count.

The next four bytes provide the file pointer which points to the data comprising the object.

3 RASTER: This indicates that the number of rows andcolumns is greater than one and the data are just a partof a larger raster object. This would be the case for blocksof images which are written to the file.

15

integer (16 bits)

byte 11 byte 10

0

31

integer (32 bit)


0

31

integer (32 bit)


0

55


EMIF_M_PTR (Indication of Indirect Data)

This is used when the following data belong to an indirect reference of data of variable length.For example, when one object is defined by referring to another object. This is identical in fileformat to the EMIF_M_INDIRECT element. Its main difference is in the memory resident objectwhich gets created. In the case of the EMIF_M_PTR the count and data pointer are placed intomemory. Whereas only the data gets placed into memory when the EMIF_M_INDIRECTelement is read in. (The size of the object is inherent in the data definitions.)

The first four bytes provide the object repeat count.

The next four bytes provide the file pointer which points to the data comprising the object.

31

integer (32 bit)


0

31

integer (32 bit)


0

56


MIF Data Dictionary

IMAGINE HFA files have a data dictionary that describes the contents of each of the differenttypes of nodes. The dictionary is a compact ASCII string which is usually placed at the end of thefile. A pointer to the start of the dictionary is stored in the header of the file.

Each object is defined like a structure in C, and consists of one or more items. Each item iscomposed of an ItemType and a name. The ItemType indicates the type of data and the nameindicates the name by which the item will be known.

The syntax of the dictionary string is:

Dictionary ObjectDefini t ion[ObjectDefini t ion. . . ] .The dictionary is one or more ObjectDefinitionsterminated by a period. This is the completecollection of object type definitions.

ObjectDefinition {I temDefinit ion[ I temDefinit ion. . . ]}name ,An ObjectDefinition is an ItemDefinitionenclosed in braces {} followed by a name andterminated by a comma. This is a completedefinition of a single object.

ItemDefinition number:[ * |p] I temType[EnumData]name,An ItemDefinition is a number followed by acolon, followed optionally by either an asteriskor a p, followed by an ItemType, followedoptionally by EnumData, followed by an itemname, and terminated by a comma. This is thecomplete definition of a single Item. The * andthe p both indicate that when the data are readinto memory, they will not be placed directlyinto the structure being built, but that a newstructure will be allocated and filled with thedata. The pointer to that structure is placed intothe initial structure. The asterisk indicates thatthe number of items in the indirect object isgiven by the number in the item definition. Thep indicates that the number is variable. In bothcases, the count precedes the data in the inputstream.

57


This table describes the single character codes used to identify the ItemType in the MIFDictionary Definition. The Interpretation column describes the type of data indicated by the itemtype. The Number of Bytes column is the number of bytes that the data type will occupy in theMIF file. If the number of bytes is not fixed, then it is given as dynamic.

EnumData number :name ,[<name>,. . . ]EnumData is a number, followed by a colon,followed by one or more names each of whichis terminated by a comma. The number definesthe number of names which will follow. This isthe complete set of names associated with anindividual enum type.

name Any sequence of alphanumeric charactersexcluding the comma.

number A positive integer number. This composed ofany sequence of these digits:0,1,2,3,4,5,6,7,8,9.

ItemType 1|2|4|c|C|s|S| l|L| f|d| t|m|M|b|e|o|xThis is used to indicate the type of an item. Thefollowing table indicates how the characterscorrespond to one of the basic EMIF_T types.

ItemType Interpretation Number of

Bytes

1 EMIF_T_U1 1

2 EMIF_T_U2 1

4 EMIF_T_U4 1

c EMIF_T_UCHAR 1

C EMIF_T_CHAR 1

e EMIF_T_ENUM. 2

s EMIF_T_USHORT 2

S EMIF_T_SHORT 2

t EMIF_T_TIME 4

l EMIF_T_ULONG 4

L EMIF_T_LONG 4

f EMIF_T_FLOAT 4

58


d EMIF_T_DOUBLE 8

m EMIF_T_COMPLEX 8

M EMIF_T_DCOMPLEX 16

b EMIT_T_BASEDATA dynamic

o Previously defined object. Thisindicates that the description of thefollowing data has been previouslydefined in the dictionary. This is likeusing a previously defined structure ina structure definition.

dynamic

x Defined object for this entry. Thisindicates that the description of thefollowing data follows. This is likeusing a structure definition within astructure definition.

dynamic

ItemType Interpretation Number of

Bytes

59



The following section defines the list of objects which comprise ERDAS IMAGINE image files(.img extension). This is not a complete list because users and developers may create new itemsand add them to any ERDAS IMAGINE file.

The image files created and used by ERDAS IMAGINE are stored in a hierarchical filearchitecture (HFA). This format allows any number of different types of data elements to bestored in the file in a tree structured fashion. This tree is built of nodes which contain a variety oftypes of data. The contents of the nodes (as well as the structural information) is saved in the filein a machine independent format (MIF) which allows the files to be shared between computersof differing architectures.

Hierarchical File Architecture

The hierarchical file architecture maintains an object-oriented representation of data in anERDAS IMAGINE disk file through use of a tree structure. Each object is called an entry andoccupies one node in the tree. Each object has a name and a type. The type refers to adescription of the data contained by that object. Additionally each object may contain a pointerto a subtree of more nodes. All entries are stored in MIF and can be accessed directly by name.

Figure 6: HFA File Structure

Header

Dictionary Root Node

Node_1 Node_2 Node_3

Data Data

Data

Node_4 Node_5

Data

Data

60


Nodes and Objects

Each node within the HFA tree structure contains an object and each object has its own data.The types of objects in a file are dependent upon the type of file. For example, a .img file will havedifferent objects than an .ovr file because these files store different types of data. The list ofobjects in a file is not fixed. Objects may be added or removed depending on the data in the file(e.g., not every .img file with continuous raster layers will have a node for ground control points).

Figure 9, below, is an example of an HFA file structure for a thematic raster layer in a .img file. Ifthere were more attributes in the ERDAS IMAGINE Raster Attribute Editor, then they wouldappear as objects under the Descriptor Table object.

Figure 7: HFA File Structure Example

Layer_1 Eimg_Layer

StatisticsEsta_Statistics

DescriptorTableEdsc_Table

ProjectionEprj_ProParameters

#BinFunction#Edsc_BinFunction

RedEdsc_Column

GreenEdsc_Column

BlueEdsc_Column

Class_NamesEdsc_Column

HistogramEdsc_Column

61


Pre-defined HFA File Object Types

There are three categories of pre-defined HFA File Object Types found in .img files:

♦ Basic HFA File Object Types

♦ .img Object Types

♦ External File Format Header Object Types

These sections list each object with two different detailed definitions. The first definition showsyou how the object appears in the data dictionary in the HFA file. The second definition is a tablethat shows you the type, name, and description of each item in the object. An item within anobject can be an element or another object.

i If an item is an element, then the item type is one of the basic types previously given with theEMIF_T_ prefix omitted. For example, the item type for EMIF_T_CHAR would be shown asCHAR.

If an item is a previously defined object type, then the type is simply the name of the previouslydefined item.

If the item is an array, then the number of elements is given in square brackets [n] after the type.For example, the type for an item with an array of 16 EMIF_T_CHAR would appear as CHAR[16].If the item is an indirect item of fixed size (it is a pointer to an item), then the type is followed byan asterisk “*.” For example, a pointer to an item with an array of 16 EMIF_T_CHAR wouldappear as CHAR[16] *. If the item is an indirect item of variable size (it is a pointer to an item andthe number of items), then the type is followed by a “p.” For example, a pointer to an item with avariable sized array of characters would look like CHAR p.

i If the item type is shown as PTR, then this item will be encoded in the data dictionary as aULONG element.

62


Basic Objects of an HFA File

This is a list of types of basic objects found in all HFA files:

♦ Ehfa_HeaderTag

♦ Ehfa_File

♦ Ehfa_Entry

Ehfa_HeaderTag

The Ehfa_HeaderTag is used as a unique signature at the beginning of an ERDAS IMAGINEHFA file. It must always occupy the first 20 bytes of the file.

{16:clabel,1:lheaderPtr,}Ehfa_HeaderTag,

Ehfa_File

The Ehfa_File is composed of several main parts, including the free list, the dictionary, and theobject tree. This entry is used to keep track of these items in the file, since they may beginanywhere in the file.

{1:Lversion,1:lfreeList,1:lrootEntryPtr,1:SentryHeaderLength,1:ldictionaryPtr,}Ehfa_File,

Type Name Description

CHAR[16] label This contains the string“EHFA_HEADER_TAG”

PTR headerPtr The file pointer to the Ehfa_File headerrecord.


LONG version This defines the version number of the ehfafile. It is currently 1.

PTR freeList This points to list of freed blocks within the file.This list is searched first whenever new spaceis needed. As blocks of space are released inthe file, they are placed on the free list so thatthey may be reused later.

PTR rootEntryPtr This points to the root node of the object tree.

63


Ehfa_Entry

The Ehfa_Entry contains the header information for each node in the object tree, including thename and type of the node as well as the parent/child information.

{1:lnext,1:lprev,1:lparent,1:lchild,1:ldata,1LdataSize,64:cname,32:ctype,1:tmodTime,}Ehfa_Entry,

SHORT entryHeaderLength This defines the length of the entry portion ofeach node. Each node consists of two parts.The first part is the entry which contains thenode name, node type, and parent/childinformation. The second part is the data forthe node.

PTR dictionaryPtr This points to the starting position of the file forthe MIF Dictionary. The dictionary must beread and decoded before any of the otherobjects in the file can be decoded.


PTR next This is a file pointer which gives the locationof the next node in the tree at the currentlevel. If this is the last node at this level, thenthis contains 0.

PTR prev This is a file pointer which gives the locationof the previous node in the tree at the currentlevel. If this is the first node at this level, thenthis contains 0.

PTR parent This is a file pointer which gives the locationof the parent for this node. This is 0 for theroot node.

PTR child This is a file pointer which gives the locationof the first of the list of children for this node.If there are no children, then this contains 0.

PTR data This points to the data for this node. If thereis no data for this node then it contains 0.

LONG dataSize This contains the number of bytes containedin the data record associated with this node.


64


CHAR[64] name This contains a NULL terminated string thatis the name for this node. The string can beno longer then 64 bytes including the NULLterminator byte.

CHAR[32] type This contains a NULL terminated stringwhich names the type of data to be found atthis node. The type must match one of thetypes found in the data dictionary. The typename can be no longer then 32 bytesincluding the NULL terminator byte.

TIME modTime This contains the time of the last modificationto the data in this node.


65


Objects of a .img File

This is a list of types of pre-defined objects commonly found in .img HFA files:

♦ Eimg_Layer

♦ Eimg_Layer_SubSample

♦ Eimg_NonInitializedValue

♦ Ehfa_Layer

♦ Edms_VirtualBlockInfo

♦ Edms_FreeIDList

♦ Edms_State

♦ Edsc_Table

♦ Edsc_BinFunction

♦ Edsc_Column

♦ Eded_ColumnAttributes_1

♦ Esta_Statistics

♦ Esta_Covariance

♦ Esta_SkipFactors

♦ Esta_ExcludedValues

♦ Eprj_Datum

♦ Eprj_Spheroid

♦ Eprj_ProParameters

♦ Eprj_Coordinate

♦ Eprj_Size

♦ Eprj_MapInfo

♦ Efga_Polynomial

66


♦ Calibration_Node

Eimg_Layer

An Eimg_Layer object is the base node for a single layer of imagery. This object describes thebasic information for the layer, including its width and height in pixels, its data type, and the widthand height of the blocks used to store the image. Other information such as the actual pixel data,map information, projection information, etc., are stored as child objects under this node. Thechild objects that are usually found under the Eimg_Layer include:

♦ RasterDMS (an Edms_State which actually contains the imagery)

♦ Descriptor_Table (an Edsc_Table object which contains the histogram and other pixel valuerelated data)

♦ Projection (an Eprj_ProParameters object which contains the projection information)

♦ Map_Info (an Eprj_MapInfo object which contains the map information)

♦ Ehfa_Layer (an Ehfa_Layer object which describes the type of data in the layer)

{1:lwidth,1:lheight,1:e3:thematic,athematic,fft of real valued data,layerType,1e13:u1,u2,u4,u8, s8,u16,s16,u32,s32,f32,f64,c64,c128,pixelType,1:lblockWidth,1:lblockHeight,} Eimg_Layer,


LONG width The width of the layer in pixels.

LONG height The height of the layer in pixels.

ENUM layerType The type of layer. 0=”thematic” 1=”athematic”

67


Eimg_Layer_SubSample

An Eimg_Layer_SubSample object is a node which contains a subsampled version of the layerdefined by the parent node. The node of this form are named _ss_2, _ss_4, _ss_8, etc. Thisstands for SubSampled by 2, SubSampled by 4, etc. This node will have an Edms_State nodecalled RasterDMS and an Ehfa_Layer node called Ehfa_layer under it. This will be present ifpyramid layers have been computed.

{1:lwidth,1:lheight,1:e3:thematic,athematic,fft of real valued data,layerType,1e13:u1,u2,u4,u8, s8,u16,s16,u32,s32,f32,f64,c64,c128,pixelType,1:lblockWidth,1:lblockHeight,} Eimg_Layer_SubSample,

ENUM pixelType The type of the pixels.0=”u1”1=”u2”2=”u4”3=”u8”4=”s8”5=”u16”6=”s16”7=”u32”8= ”s32”9=”f32”10=”f64”11=”c64”12=”c128”

LONG blockWidth The width of each block in the layer.

LONG blockHeight The height of each block in the layer.


LONG width The width of the layer in pixels.

LONG height The height of the layer in pixels.

ENUM layerType The type of layer. 0 =”thematic” 1 =”athematic”


68


Eimg_NonInitializedValue

The Eimg_NonInitializedValue object is used to record the value that is to be assigned to anyuninitialized blocks of raster data in a layer.

{1:*bvalueBD,}Eimg_NonInitializedValue,

Ehfa_Layer

The Ehfa_Layer is used to indicate the type of layer. The initial design for the IMAGINE filesallowed for both raster and vector layers. Currently, the vector layers have not beenimplemented.

ENUM pixelType The type of the pixels.0=”u1”1=”u2”2=”u4”3=”u8”4=”s8”5=”u16”6=”s16”7=”u32”8=”s32”9=”f32”10=”f64”11=”c64”12=”c128”

LONG blockWidth The width of each block in the layer.

LONG blockHeight The height of each block in the layer.


BASEDATA * valueBD A basedata structure containing the excludedvalues


69


{1:e2:raster,vector,type,1:ldictionaryPtr,}Ehfa_Layer,

RasterDMS

The RasterDMS object definition must be present in the EMIF dictionary pointed to by anEhfa_Layer object that is of type “raster”. It describes the logical make-up of a block of rasterdata in the Ehfa_Layer. The physical representation of the raster data is actually managed bythe DMS system through objects of type Ehfa_Layer and Edms_State. The RasterDMS definitionshould describe the raster data in terms of total number of data values in a block and the type ofdata value.

{<n>:<t>data,}RasterDMS,


ENUM type The type of layer.0=”raster”1=”vector”

ULONG dictionaryPtr This points to a dictionary entry whichdescribes the data. In the case of raster data,it points to a dictionary pointer whichdescribes the contents of each block via theRasterDMS definition given below.


<t>[<n>] data The data is described in terms of total number, <n>, of datafile values in a block of the raster layer (which is simply<block width> * <block height>) and the data value type,<t>, which can have any one of the following values:

1 - Unsigned 1-bit2 - Unsigned 2-bit4 - Unsigned 4-bitc - Unsigned 8-bitC - Signed 8-bits - Unsigned 16-bitS - Signed 16-bitl - Unsigned 32-bitL - Signed 32-bitf - Single precision floating pointd - Double precision floating pointm - Single precision complexM - Double precision complex

70


Edms_VirtualBlockInfo

An Edms_VirtualBlockInfo object describes a single raster data block of a layer. It describeswhere to find the data in the file, how many bytes are in the data block, and how to unpack thedata from the block. For uncompressed data the unpacking is straight forward. The scheme forcompressed data is described below.

{1:SfileCode,1:loffset,1:lsize,1:e2:false,true,logvalid,1:e2:no compression,ESRI GRIDcompression,compressionType,1:LblockHeight,}Edms_VirtualBlockInfo,

For uncompressed blocks, the data are simply packed into the block one pixel value at a time.Each pixel is read from the block as indicated by its data type. All non-integer data areuncompressed.

The compression scheme used by ERDAS IMAGINE is a two level run-length encoding scheme.If the data are an integral type, then the following steps are performed:


SHORT fileCode This is included to allow expansion of the layerinto multiple files. The number indicates thefile in which the block is located. Currently thisis always 0, since the multiple file scheme hasnot been implemented.

PTR offset This points to the byte location in the filewhere the block data actually resides.

LONG size The number of bytes in the block.

ENUM logvalid This indicates whether the block actuallycontains valid data. This allows blocks to existin the map, but not in the file.0=”false”1=”true”

ENUM compressionType This indicates the type of compression usedfor this block.0=”no compression”1=”ESRI GRID compression”No compression indicates that the datalocated at offset are uncompressed data. Thestream of bytes is to be interpreted as asequence of bytes which defines the data asindicated by the data type.The ESRI GRID compression is a two stagerun-length encoding.

71


♦ The minimum and maximum values for a block are determined.

♦ The byte size of the output pixels is determined by examining the difference between themaximum and the minium. If the difference is less than or equal to 256, then 8-bit data areused. If the difference is less than 65,536 then, 16-bit data are used, otherwise 32-bit dataare used.

♦ The minimum is subtracted from each of the values.

♦ A run-length encoding scheme is used to encode runs of the same pixel value. The dataminimum value occupies the first 4 bytes of the block. The number of run-length segmentsoccupies the next 4 bytes, and the next 4 bytes are an offset into the block which indicateswhere the compressed pixel values begin. The next byte indicates the number of bits per pixel(1,2,4,8,16,32). These four values are encoded in the standard MIF format (ULONG).Following this is the list of segment counts, following the segment counts are the pixel values.There is one segment count per pixel value.

i No compression scheme is used if the data are non-integral.

Each data count is encoded as follows:

There may be 1, 2, 3, or 4 bytes per count. The first two bits of the first count byte contains 0,1,2,3indicating that the count is contained in 1, 2,3, or 4 bytes. Then the rest of the byte (6 bits)represent the six most significant bytes of the count. The next byte, if present, representsdecreasing significance.

i This order is different than the rest of the package. This was done so that the high byte withthe encoded byte count would be first in the byte stream. This pattern is repeated as manytimes as indicated by the numsegments field.

The data values are compressed into the remaining space packed into as many bits per pixel asindicated by the numbitpervalue field.

min numsegments

dataoffset

numbitsper value

data counts data values

next 8 bits next 8 bits next 8 bits bytecount

high 6 bits


72


Edms_FreeIDList

An Edms_FreeIDList is used to track blocks which have been freed from the layer. The freelistconsists of an array of min/max pairs which indicate unused contiguous blocks of data which liewithin the allocated layer space. Currently this object is unused and reserved for futureexpansion.

{1:Lmin,1:Lmax,}Edms_FreeIDList,

Edms_State

The Edms_State describes the location of each of the blocks of a single layer of imagery.Basically, this object is an index of all of the blocks in the layer.

{1:lnumvirtualblocks,1:lnumobjectsperblock,1:lnextobjectnum,1:e2:no compression,RLC compression,compressionType,0:poEdms_VirtualBlockInfo,blockinfo,0:poEdms_FreeIDList,freelist,1:tmodTime,}Edms_State,


LONG min The minimum block number in the group.

LONG max The maximum block number in the group.


LONG numvirtualblocks

The number of blocks in thislayer.

LONG numobjectsperblock

The number of pixelsrepresented by one block.

LONG nextobjectnum Currently, this type is not beingused and is reserved for futureexpansion.

73


Edsc_Table

An Edsc_Table is a base node used to store columns of information. This serves simply as aparent node for each of the columns which are a part of the table.

{1:lnumRows,} Edsc_Table,

Edsc_BinFunction

The Edsc_BinFunction describes how pixel values from the associated layer are to be mappedinto an index for the columns.

ENUM compressionType This indicates the type ofcompression used for this block.0=”no compression”1=”ESRI GRID compression”No compression indicates thatthe data located at offset areuncompressed data. The streamof bytes is to be interpreted as asequence of bytes which definesthe data as indicated by the datatype.The ESRI GRID compression isa two stage run-length encoding.

Edms_VirtualBolckInfo p blockinfo This is the table of entries whichdescribes the state and locationof each block in the layer.

Edms_FreeIDList p freelist Currently, this type is not beingused and is reserved for futureexpansion.

TIME modTime This is the time of the lastmodification to this layer.


LONG numRows This defines the number of rows in the table.


74


{1:lnumBins,1:e4:direct,linear,logarithmic,explicit,binFunction Type,1:dminLimit,1:dmaxLimit,1:*bbinLimits,} Edsc_BinFunction,

The following table describes how the binning functions are used.

Edsc_Column

The columns of information which are stored in a table are stored in this format.


LONG numBins The number of bins.

ENUM binFunction Type The type of bin function.0=”direct”1=”linear”2=”exponential”3=”explicit”

DOUBLE minLimit The lowest value defined by the bin function.

DOUBLE maxLimit The highest value defined by the binfunction.

BASEDATA binLimits The limits used to define the bins.

Bin Type Description

DIRECT Direct binning means that the pixel value minus theminimum is used as is with no translation to index into thecolumns. For example, if the minimum value is zero, thenvalue 0 is indexed into location 0, 1 is indexed into 1, etc.

LINEAR Linear binning means that the pixel value is first scaled bythe formula:index = (value-minLimit)*numBins/(maxLimit-minLimit).This allows a very large range of data, or even floating pointdata, to be used to index into a table.

EXPONENTIAL Exponential binning is used to compress data with a largedynamic range. The formula used is index =numBins*(log(1+(value-minLimit)) / (maxLimit-minLimit).

EXPLICIT Explicit binning is used to map the data into indices usingan arbitrary set of boundaries. The data are comparedagainst the limits set in the binLimit table. If the pixel is lessthan or equal to the first value, then the index is 0. If thepixel is less than or equal to the next value, then the index is1, etc.

75


{1:lnumRows,1:LcolumnDataPtr,1:e4:integer,real,comples,string,dataType,1:lmaxNumChar,} Edsc_Column,

The types of information stored in columns are given in the following table.


LONG numRows The number of rows in this column.

PTR columnDataPtr Starting point of column data in the file. Thispoints to the location in the file which containsthe data.

ENUM dataType The data type of this column0=”integer” (EMIF_T_LONG)1=”real” (EMIF_T_DOUBLE)2=”complex” (EMIF_T_DCOMPLEX)3=”string” (EMIF_T_CHAR)

LONG maxNumChars The maximum string length (for string dataonly). It is 0 if the type is not a String.

Name Data Type Description

Histogram real This is found in the descriptor table of almostevery layer. It defines the number of pixelswhich fall into each bin.

Class_Names string This is found in the descriptor table of almostevery thematic layer. It defines the name foreach class.

Red real This is found in the descriptor table of almostevery thematic layer. It defines the redcomponent of the color for each class. Therange of the value is from 0.0 to 1.0.

Green real This is found in the descriptor table of almostevery thematic layer. It defines the greencomponent of the color for each class. Therange of the value is from 0.0 to 1.0.

Blue real This is found in the descriptor table of almostevery thematic layer. It defines the bluecomponent of the color for each class. Therange of the value is from 0.0 to 1.0.

76


Eded_ColumnAttributes_1

The Eded_ColumnAttributes_1 stores the descriptor column properties which are used by theRaster Attribute Editor for the format and layout of the descriptor column display in the RasterAttribute Editor CellArray. The properties include the position of the descriptor column within theCellArray, the name, alignment, format, and width of the column, whether the column is editable,the formula (if any) for the column, the units (for numeric data), and whether the column is acomponent of a color column. Each Eded_ColumnAttributes_1 is a child of the Edsc_Columncontaining the data for the descriptor column. The properties for a color column are stored as achild of the Eded_ColumnAttributes_1 for the red component of the color column.

Opacity real This is found in the descriptor table of almostevery thematic layer. It defines the opacityassociated with the class. A value of 0 meansthat the color will be solid. A value of 0.5 meanthat 50% of the underlying pixel would showthrough, and 1.0 means that all of the pixelvalue in the underlying layer would showthrough.

Contrast real This is found in the descriptor table of mostcontinuous raster layers. It is used to define anintensity stretch which is normally used toimprove contrast. The table is stored asnormalized values from 0.0 to 1.0.

GCP_Names string This is found in the GCP_Table in files whichhave ground control points. This is the table ofnames for the points.

GCP_xCoords real This is found in the GCP_Table in files whichhave ground control points. This is the Xcoordinate for the point.

GCP_yCoords real This is found in the GCP_Table in files whichhave ground control points. This is the Ycoordinate for the point.

GCP_Color string This is found in the GCP_Table in files whichhave ground control points. This is the nameof the color that is used to display this point.

Name Data Type Description

77


{1:lposition,0:pcname,1:e2:FALSE,TRUE,editable,1:e3:LEFT,CENTER,RIGHT,alignment,0:pcformat,1:e3:DEFAULT,APPLY,AUTO-APPLY,formulamode,0:pcformula,1:dcolumnwidth,0:pcunits,1:e5:NO_COLOR,RED,GREEN,BLUE,COLOR,colorflag,0:pcgreenname,0:pcbluename,}Eded_ColumnAttributes_1,


LONG position The position of this descriptor column in theRaster Attribute Editor CellArray. The positionsfor all descriptor columns are sorted and thecolumns are displayed in ascending order.

CHAR P name The name of the descriptor column. This is thesame as the name of the parent Edsc_Columnnode, for all columns except color columns,Color columns have no correspondingEdsc_Column.

ENUM editable Specifies whether this column is editable.0 = NO1 = YES

ENUM alignment Alignment of this column in CellArray.0 = LEFT1 = CENTER2 = RIGHT

CHAR P format The format for display of numeric data.

ENUM formulamode Mode for formula application.0 = DEFAULT1 = APPLY2 = AUTO-APPLY

CHAR P formula The formula for the column.

DOUBLE columnwidth The width of the CellArray column

CHAR P units The name of the units for numeric data storedin the column.

ENUM colorflag Indicates whether column is a color column, acomponent of a color column, or a normalcolumn.0 = NO_COLOR1 = RED2 = GREEN3 = BLUE4 = COLOR

78


Esta_Statistics

The Esta_Statistics is used to describe the statistics for a layer.

{1:dminimum,1:dmaximum,1:dmean,1:dmedian,1d:mode,1:dstddev,}Esta_Statistics,

Esta_Covariance

The Esta_Covariance object is used to record the covariance matrix for the layers in a .img file

CHAR P greenname Name of green component column associatedwith color column. Empty string for othercolumn types.

CHAR P bluename Name of blue component column associatedwith color column. Empty string for othercolumn types.


DOUBLE minimum The minimum of all of the pixels in the image.This may exclude values as defined by theuser.

DOUBLE maximum The maximum of all of the pixels in the image.This may exclude values as defined by theuser.

DOUBLE mean The mean of all of the pixels in the image. Thismay exclude values as defined by the user.

DOUBLE median The median of all of the pixels in the image.This may exclude values as defined by theuser.

DOUBLE mode The mode of all of the pixels in the image. Thismay exclude values as defined by the user.

DOUBLE stddev The standard deviation of the pixels in theimage. This may exclude values as defined bythe user.


79


{1:bcovariance,}Esta_Covariance,

Esta_SkipFactors

The Esta_SkipFactors object is used to record the skip factors that were used when the statisticsor histogram was calculated for a raster layer or when the covariance was calculated for a .imgfile.

{1:LskipFactorX,1:LskipFactorY,}Esta_SkipFactors,

Esta_ExcludedValues

The Esta_ExcludedValues object is used to record the values that were excluded fromconsideration when the statistics or histogram was calculated for a raster layer or when thecovariance was calculated for a .img file.

{1:*bvalueBD,}Esta_ExcludedValues,

Eprj_Datum

The Eprj_Datum object is used to record the datum information which is part of the projectioninformation for a .img file.


BASEDATA covariance A basedata structure containing thecovariance matrix


LONG skipFactorX The horizontal sampling interval used forstatistics measured in image columns/sample

LONG skipFactorY The vertical sampling interval used for statisticsmeasured in image rows/sample


BASEDATA * valueBD A basedata structure containing the excludedvalues

80


{0:pcdatumname,1:e3:EPRJ_DATUM_PARAMETRIC,EPRJ_DATUM_GRID,EPRJ_DATUM_REGRESSION,type,0:pdparams,0:pcgridname,}Eprj_Datum,

Eprj_Spheroid

The Eprj_Spheroid is used to describe spheroid parameters used to describe the shape of theearth.

{0:pcsphereName,1:da,1:db,1:deSquared,1:dradius,}Eprj_Spheroid,

Eprj_ProParameters

The Eprj_Parameters is used to define the map projection for a layer.


CHAR datumname The datum name.

ENUM type The datum type which could be one of threedifferent types: parametric type, grid type andregression type.

DOUBLE params The seven parameters of a parametric datumwhich describe the translations, rotations andscale change between the current datum andthe reference datum WGS84.

CHAR gridname The name of a grid datum file which stores thecoordinate shifts among North AmericaDatums NAD27, NAD83 and HARN.


CHAR p sphereName The name of the spheroid/ellipsoid. This nameis can be found in:<IMAGINE_HOME>/etc/spheroid.tab.

DOUBLE a The semi-major axis of the ellipsoid in meters.

DOUBLE b The semi-minor axis of the ellipsoid in meters.

DOUBLE eSquared The eccentricity of the ellipsoid, squared.

DOUBLE radius The radius of the spheroid in meters.

81


{1:e2:EPRJ_INTERNAL,EPRJ_EXTERNAL,proType,1:lproNumber,0:pcproExeName,0:pcproName,1:lproZone,0:pdproParams,1:*oEprj_Spheroid,proSpheroid,}Eprj_ProParameters,


ENUM proType This defines whether the projection is internalor external.0=”EPRJ_INTERNAL”1=” EPRJ_EXTERNAL”

LONG proNumber The projection number for internal projections.The current internal projections are:0=”Geographic(Latitude/Longitude)”1=”UTM”2=”State Plane”3=”Albers Conical Equal Area”4=”Lambert Conformal Conic”5=”Mercator”6=”Polar Stereographic”7=”Polyconic”8=”Equidistant Conic”9=”Transverse Mercator”10=”Stereographic”11=”Lambert Azimuthal Equal-area”12=”Azimuthal Equidistant”13=”Gnomonic”14=”Orthographic”15=”General Vertical Near-Side Perspective”16=”Sinusoidal”17=”Equirectangular”18=”Miller Cylindrical”19=”Van der Grinten I”20=”Oblique Mercator (Hotine)”21=”Space Oblique Mercator”22=”Modified Transverse Mercator”

CHAR p proExeName The name of the executable to run for anexternal projection.

CHAR p proName The name of the projection. This will be one ofthe names given above in the description ofproNumber.

LONG proZone The zone number for internal State Plane orUTM projections.

DOUBLE p proParams The array of parameters for the projection.

82


The following table defines the contents of the proParams array which is defined above. TheParameters column defines the meaning of the various elements of the proParams array for thedifferent projections. Each one is described by one or more statements of the form n: Description.n is the index into the array.

Eprj_Spheroid * proSpheroid The parameters of the spheroid used toapproximate the earth. See the description forthe Eprj_Spheroid object, above.

Name Parameters

0 ”Geographic(Latitude/Longitude)”

None Used

1 ”UTM” 3: 1=North, -1=South

2 ”State Plane” 0: 0=NAD27, 1=NAD83

3 ”Albers Conical Equal Area” 2: Latitude of 1st standard parallel3: Latitude of 2nd standard parallel4: Longitude of central meridian5: Latitude of origin of projection6: False Easting7: False Northing

4 ”Lambert Conformal Conic” 2: Latitude of 1st standard parallel3: Latitude of 2nd standard parallel4: Longitude of central meridian5: Latitude of origin of projection6: False Easting7: False Northing

5 ”Mercator” 4: Longitude of central meridian5: Latitude of origin of projection6: False Easting7: False Northing

6 ”Polar Stereographic” 4: Longitude directed straight down below poleof map.

5: Latitude of true scale.6: False Easting7: False Northing.


83


7 ”Polyconic” 4: Longitude of central meridian5: Latitude of origin of projection6: False Easting7: False Northing

8 ”Equidistant Conic” 2: Latitude of standard parallel (Case 0)2: Latitude of 1st Standard Parallel (Case 1)3: Latitude of 2nd standard Parallel (Case 1)4: Longitude of central meridian5: Latitude of origin of projection6: False Easting7: False Northing8: 0=Case 0, 1=Case 1.

9 ”Transverse Mercator” 2: Scale Factor at Central Meridian4: Longitude of center of projection5: Latitude of center of projection6: False Easting7: False Northing

10 ”Stereographic” 4: Longitude of center of projection5: Latitude of center of projection6: False Easting7: False Northing

11 ”Lambert Azimuthal Equal-area”

4: Longitude of center of projection5: Latitude of center of projection6: False Easting7: False Northing

12 ”Azimuthal Equidistant” 4: Longitude of center of projection5: Latitude of center of projection6: False Easting7: False Northing

13 ”Gnomonic” 4: Longitude of center of projection5: Latitude of center of projection6: False Easting7: False Northing

14 ”Orthographic” 4: Longitude of center of projection5: Latitude of center of projection6: False Easting7: False Northing

Name Parameters

84


15 ”General Vertical Near-SidePerspective

2: Height of perspective point above sphere.4: Longitude of center of projection5: Latitude of center of projection6: False Easting7: False Northing

16 ”Sinusoidal” 4: Longitude of central meridian6: False Easting7: False Northing

17 ”Equirectangular” 4: Longitude of central meridian5: Latitude of True Scale.6: False Easting7: False Northing

18 ”Miller Cylindrical” 4: Longitude of central meridian6: False Easting7: False Northing

19 ”Van der Grinten I” 4: Longitude of central meridian6: False Easting7: False Northing

20 ”Oblique Mercator (Hotine)” 2: Scale Factor at center of projection3: Azimuth east of north for central line. (Case

1)4: Longitude of point of origin (Case 1)5: Latitude of point of origin.6: False Easting7: False Northing.8: Longitude of 1st Point defining central line

(Case 0)9: Latitude of 1st Point defining central line

(Case 0)10: Longitude of 2nd Point defining central

line. (Case 0)11: Latitude of 2nd Point defining central line

(Case 0).12: 0=Case 0, 1=Case 1

21 ”Space Oblique Mercator” 4: Landsat Vehicle ID (1-5)5: Orbital Path Number (1-251 or 1-233)6: False Easting7: False Northing

Name Parameters

85


Eprj_Coordinate

An Eprj_Coordiante is a pair of doubles used to define X and Y.

{1:dx,1:dy,}Eprj_Coordinate,

Eprj_Size

The Eprj_Size is a pair of doubles used to define a rectangular size.

{1:dx,1:dy,}Eprj_Size,

Eprj_MapInfo

The Eprj_MapInfo object is used to define the basic map information for a layer. It defines themap coordinates for the center of the upper left and lower right pixels, as well as the cell size andthe name of the map projection.

{0:pcproName,1:*oEprj_Coordinate,upperLeftCenter,1:*oEprj_Coordinate,lowerRightCenter,1:*oEprj_Size,pixelSize,0:pcunits,}Eprj_MapInfo,

22 ”Modified TransverseMercator”

6: False Easting7: False Northing


DOUBLE x The X value of the coordinate.

DOUBLE y The Y value of the coordinate.


DOUBLE width The X value of the coordinate.

DOUBLE height The Y value of the coordinate.


CHAR p proName The name of the projection.

Eprj_Coordinate *

upperLeftCenter The coordinates of the center of the upper leftpixel.

Name Parameters

86


Efga_Polynomial

The Efga_Polynomial is used to store transformation coefficients created by the IMAGINE GCPEditor.

{1:Lorder,1:Lnumdimtransforms,1:numdimpolynomial,1:Ltermcount,1:*exponentList,1:bpolycoefmtx,1:bpolycoefvector,}Efga_Polynomial,

Eprj_Coordinate *

lowerRightCenter The coordinates of the center of the lowerright pixel.

Eprj_Size * pixelSize The size of the pixel in the image.

CHAR * units The units of the above values.


LONG order The order of the polynomial.

LONG numdimtransform The number of dimensions of thetransformation (always 2).

LONG numdimpolynomial The number of dimensions of thepolynomial (always 2).

LONG termcount The number of terms in the polynomial.

LONG * exponentlist The ordered list of powers for thepolynomial.

BASEDATA polycoefmtx The polynomial coefficients.

BASEDATA polycoefvector The polynomial vectors.


87


Calibration_Node

An object of type Calibration_Node is an empty object — it contains no data. A node of this typesimply serves as the parent node of four related child objects. The children of theCalibration_Node are used to provide information which converts pixel coordinates to mapcoordinates and vice versa.There is no dictionary definition for this object type. A node of thistype will be a child of the root node and will be named “Calibration.” The “Calibration” node willhave the four children described below.

Node Object Type Description

Projection Eprj_ProParameters The projection associated withthe output coordinate system.

Map_Info Eprj_MapInfo The nominal map informationassociated with thetransformation.

InversePolynomial Efga_Polynomial This is the nth order polynomialcoefficient used to convert frommap coordinates to pixelcoordinates.

ForwardPolynomial Efga_Polynomial This is the nth order polynomialused to convert from pixelcoordinates to map coordinates

88



The following sections list the types of objects found in .img HFA files that have been importedfrom external data files:

♦ ADRG Header

♦ ADRI Header

♦ AVHRR Header

♦ DEM Header

♦ DOQ Header

♦ DTED Header

♦ MSS Header

♦ SPOT Header

♦ TM Header

89


ADRG Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from an ADRG source. The fields are copied from the Volume Header file(“TRANSH01.THF”) and from the individual Distribution Rectangle (DR) headers. If the value isa string it is left unchanged. If the value is a number it is converted from ASCII to binary. Allstrings are NULL terminated. The description column indicates the source of the information. Thethree codes in the Description column represent the file name, field name, and subfield names.The filename codes are THF for Transmittal Header File and GEN for General Information File.For example, the description “THF, VDR, URF” means the URF subfield within the VDR fieldwithin the Transmittal Header File. It is assumed that the user has access to the ADRGdocuments.


CHAR[Var. Length]

Originator THF, VDR, VOOName & address of originator

CHAR[17] StockNum THF, VDR, URFDMA stock number

SHORT VolEdNum THF, VDR, EDNVolume edition number

TIME PubDate THF, VDR, DATPublication date

CHAR SecurityClassification THF, QSR, QSSSecurity classification

ENUM AgencyDeterminationReqd THF, QSR, QODOriginating agency’s determinationrequiredNO or YES

TIME DowngradeDate THF, QSR, DATDate of downgrading

CHAR[Var. Length]

Releasability THF, QSR, QLEReleasability statement

CHAR[Var. Length]

SpecIdent THF, QUV, SRCSpecification identification for ADRG

TIME SpecDate THF, QUV, DATSpecification date

90


CHAR[21] SpecAmendmentNum THF, QUV, SPAADRG Specification amendmentnumber

CHAR[9] DistRectName THF, FDR, NAMName of the DR directory

CHAR[13] ImageName GEN(OVERVIEW_RECORD),SPR,BAD orGEN(GENERAL_INFORMATION_RECORD), SPR, BAD orSOU,SPR,BADName of the image file

ENUM ImageType Type of imageUNKNOWN, ZDR, LEGEND orOVERVIEW

SHORT Zone GEN, GEN, ZNAARC Zone number


91


ADRI Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from an ADRI source. The fields are copied from the Volume Header file and from theindividual Distribution Rectangle (DR) headers. If the value is a string it is left unchanged. If thevalue is a number it is converted from ASCII to binary. All strings are NULL terminated. Thedescription column indicates the source of the information. The three codes in the Descriptioncolumn represent the file name, field name, and subfield names. The file name codes are THFfor Transmittal Header File, GEN for General Information File, and QAL for Quality File. Forexample, the description “QAL, QUP, SPA” means the SPA subfield within the QUP (Quality UpTo Dateness) field within the Quality File. Additional comments are added when necessary toavoid ambiguity. It is assumed that the user has access to the ADRI documentation.


CHAR[Var. Length] Originator THF, VDR, VOO

CHAR[17] StockNum THF, VDR, URF

SHORT VolEdNum THF, VDR, EDN

TIME PubDate THF, VDR, DAT

CHAR SecurityClassification THF, QSR, QSS

ENUM AgencyDeterminationReqd THF, QSR, QODNO or YES

TIME DowngradeDate THF, QSR, DAT

CHAR[Var. Length] Releasability THF, QSR, QLE

CHAR[Var. Length] SpecIdent THF, QUV, SRC

TIME SpecDate THF, QUV, DAT

CHAR[21] SpecAmendmentNum THF, QUV, SPA

ENUM ImageType OVERVIEW or ZDR

CHAR[9] DistRectName Name of the DR Directory

CHAR[13] ImageName Name of the Image File

SHORT DataStructureType GEN, OVI, STR orGEN, GEN, STR

DOUBLE DataDensityEW GEN, GEN, LOD

DOUBLE DataDensityNS GEN, GEN, LAD

SHORT DataDensityUnit GEN, GEN, UNI

92


DOUBLE Ulx GEN, GEN, NWO

DOUBLE Uly GEN, GEN, NWA

DOUBLE Lrx GEN, GEN, SEO

DOUBLE Lry GEN, GEN, SEA

DOUBLE Scale GEN, GEN, SCA

SHORT Zone GEN, GEN, ZNA

DOUBLE GSD GEN, GEN, PSP

ENUM Rectified GEN, GEN, IMRNO or YES

DOUBLE Asz GEN, GEN, ARV

DOUBLE Bs GEN, GEN, BRV

CHAR[Var. Length] Text GEN, GEN, TXT

struct BandInfo[Var. Length]

BandInfo GEN, BDF(See BandInfo Structuretable below)

CHAR[21] EditionNumber QAL, QUP, EDN

TIME CreationDate QAL, QUP, DAT(Creation date of ZDR)

TIME RevisionDate QAL, QUP, DAT(Date of revision/update)

SHORT RecompilationCount QAL, QUP, REC

SHORT RevisionCount QAL, QUP, REV

CHAR[Var. Length] ADRIProduct QAL, QUP, SRC

TIME ProductSpecDate QAL, QUP, DAT(ADRI product specificationdate)

CHAR[21] ProductSpecNum QAL, QUP, SPA

TIME EarliestDate QAL, QUP, DAT(Earliest date of sourceimage in DR)


93


BandInfo Structure

TIME LatestDate QAL, QUP, DAT(Latest date of source imagein DR)


CHAR[6] BandColor GEN, BDF, BID

LONG LowerEdgeWavelength GEN, BDF, WS1

LONG UpperEdgeWavelength GEN, BDF, WS2


94


AVHRR Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from an AVHRR source. The fields are copied from the TBM and Data Set Headers.Note that not all AVHRR files contain a TBM header, so the TBM fields may be empty or zero.TBM header fields are indicated in the Description column by the “TBM” designation. All stringsare NULL terminated. The description column indicates the source of the information. It isassumed that the user has access to the AVHRR documentation, “NOAA Polar Orbiter DataUsers Guide.”


CHAR[45] DataSetName TBM Data Set Name

ENUM TotalCopy TBM Total Copy?EMSC_FALSE or EMSC_TRUE

ENUM LatitudeSelected TBM Latitude select option used?EMSC_FALSE or EMSC_TRUE

SHORT BeginningLatitude TBM Beginning Latitude

SHORT EndingLatitude TBM Ending Latitude

ENUM LongitudeSelected TBM Longitude select option used?EMSC_FALSE or EMSC_TRUE

SHORT BeginningLongitude TBM Beginning Longitude

SHORT EndingLongitude TBM Ending Longitude

ENUM TimeSelected TBM Time select option used?EMSC_FALSE or EMSC_TRUE

USHORT BeginningHour TBM Beginning Hour of data set

USHORT BeginningMinute TBM Beginning Minute of data

USHORT NumMinutes TBM Number of minutes in data set

ENUM AppendedData TBM Earth location data included?

ENUM[20] ChannelsSelected TBM EMSC_FALSE orEMSC_TRUE for 20 channels

CHAR[10] SpacecraftID Satellite Name

95


ENUM DataType EIXM_AVHRR_DATATYPE_UNKNOWN,EIXM_AVHRR_LAC,EIXM_AVHRR_GAC, orEIXM_AVHRR_HRPT

ENUM TipSource EIXM_AVHRR_TIPSOURCE_UNKNOWN,EIXM_AVHRR_EMBEDDED_TIP,EIXM_AVHRR_STORED_TIP, orEIXM_AVHRR_THIRD_CDA_TIP

TIME StartTime Time code from first frame of dataprocessed for the data set

ULONG NumScans Number of data scans

TIME EndTime Time code from the last frame ofdata processed

ULONG ProcessingBlockID Processing Block ID

UCHAR CalibrationByte Ramp/Auto Calibration field

USHORT NumDataGaps Number of data gaps

USHORT NoFrameSyncWordErrorsCount Number of input data frames with noframe sync word errors

USHORT TipParityErrorsCount Number of DACS detected TIPparity errors

USHORT AuxiliarySyncErrorsCount Sum of all auxiliary sync errorsdetected in input data

UCHAR[2] CalibrationParameterID Identifies the calibration parameterinput data set

ENUM PseudoNoiseFlag Normal data = EMSC_FALSE,Pseudo Noise data = EMSC_TRUE

CHAR[10] DataSource Receiving station

ENUM TapeDirection EIXM_AVHRR_TAPE_DIR_UNKNOWN,EIXM_AVHRR_REVERSE orEIXM_AVHRR_FORWARD


96


ENUM DataMode EIXM_AVHRR_DATAMODE_UNKONWN,EIXM_AVHRR_TESTDATA orEIXM_AVHRR_FLIGHTDATA


97


DEM Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from a DEM source. The fields are copied from the Type A and Type C records. Allstrings are NULL terminated. The description column indicates the source of the information. Itis assumed that the user has access to the DEM documentation.


CHAR[41] FileName DEM quadrangle name

CHAR[41] FreeText Free format descriptor field

CHAR ProcessCode 1=GPM, 2=Manual Profile,3=DLG2DEM, 4=DCLASS

CHAR[4] SectionalIndicato Identifies 1:100000-scalesections

CHAR[5] MCOriginCode Mapping center origin code

SHORT DEMLevelCode DEM Level

SHORT ElevationPatternCode 1=regular, 2=random

SHORT GroundRefSystemCode 0=Geographic, 1=UTM,2=State Plane

SHORT Zone State Plane or UTM Zone

DOUBLE[15] ProjectionParams USGS projection parameters

SHORT PlanimetricUnitCode 0=rad, 1=ft, 2=m, 3=arc-seconds

SHORT ElevationUnitCode 1=feet, 2=meters

SHORT CoveragePolygonSides # polygon sides defining DEMcoverage

DOUBLE SWCornerX X Coordinate of SW corner

DOUBLE SWCornerY Y Coordinate of SW corner

DOUBLE NWCornerX X Coordinate of NW corner

DOUBLE NWCornerY Y Coordinate of NW corner

DOUBLE NECornerX X Coordinate of NE corner

DOUBLE NECornerY Y Coordinate of NE corner

DOUBLE SECornerX X Coordinate of SE corner

98


DOUBLE SECornerY Y Coordinate of SE corner

DOUBLE MinElevation Minimum coverage elevation

DOUBLE MaxElevation Maximum coverage elevation

DOUBLE RotationAngle CCW angle to local DEMreference system

SHORT ElevationAccuracyCode 0=unknown, 1=info in Type Crecord

DOUBLE SpatialResolutionX Spatial resolution in X direction

DOUBLE SpatialResolutionY Spatial resolution in Y direction

DOUBLE SpatialResolutionZ Spatial resolution in Z direction

SHORT ProfileRows Number of rows per elevationprofile

SHORT ProfileCols Number of columns perelevation profile

SHORT LargestPrimaryContourInterval Present only if 2 or moreprimary intervals exist

SHORT LargestPrimaryIntervalUnits 0=N.A., 1=feet, 2=meters

SHORT SmallestPrimaryContourInterval Smallest or only primarycontour interval

SHORT SmallestPrimaryIntervalUnits 1=feet, 2=meters

CHAR[5] DataSourceDate YYMM format

CHAR[5] DataInspRevDate YYMM format

CHAR InspectionRevisionFlag “I” or “R”

SHORT DataValidationFlag See USGS manual

SHORT SuspectVoidAreaFlag 0=none, 1=suspect areas,2=void areas, 3=suspect andvoid areas

SHORT VerticalDatum 1=local mean sea level,2=NGVD 29, 3=NAVD 88


99


SHORT HorizontalDatum 1=NAD 27, 2=WGS 72,3=WGS 84, 4=NAD 83, 5=OldHawaii Datum, 6=Puerto RicoDatum, 7=NAD 83 Provisional

SHORT DataEdition Primarily DMA Specific field

SHORT DatumStatsAvailable 1=available, 0=unavailable

SHORT DatumAccuracyX In PlanimetricUnitCode units

SHORT DatumAccuracyY In PlanimetricUnitCode units

SHORT DatumAccuracyZ In ElevationUnitCode units

LONG DatumSampleSize 0=accuracy assumed to beestimated

SHORT DemStatsAvailable 1=available, 0=unavailable

SHORT DemAccuracyX In PlanimetricUnitCode units

SHORT DemAccuracyY In PlanimetricUnitCode units

SHORT DemAccuracyZ In ElevationUnitCode units

LONG DemSampleSize 0=accuracy assumed to beestimated


100


DOQ Header

The following table defines the contents of the record written to an ERDAS IMAGINE .img filewhich has been read from a USGS DOQ (Digital Ortho Quadrangle) source. The fields arecopied from the four DOQ header records. All strings are NULL terminated. It is assumed thatthe user has access to the DOQ documentation.


CHAR[39] quadrangleName Authorized quadrangle name

CHAR[3] quadrant Quadrangle quadrant (SW, NW, NE,SE)

CHAR[3] nation1 FIPS nation code, primary nation

CHAR[3] nation2 FIPS nation code, secondary nation

CHAR[3] state1 First state in file

CHAR[3] state2 Second state in file

CHAR[3] state3 Third state in file

CHAR[3] state4 Fourth state in file

CHAR[4] state1county1 First county in first state

CHAR[4] state1county2 Second county in first state

CHAR[4] state1county3 Third county in first state

CHAR[4] state1county4 Fourth county in first state

CHAR[4] state1county5 Fifth county in first state

CHAR[4] state2county1 First county in second state

CHAR[4] state2county2 Second county in second state

CHAR[4] state2county3 Third county in second state

CHAR[4] state2county4 Fourth county in second state

CHAR[4] state2county5 Fifth county in second state

CHAR[4] state3county1 First county in third state

CHAR[4] state3county2 Second county in third state

CHAR[4] state3county3 Third county in third state

CHAR[4] state3county4 Fourth county in third state

101


CHAR[4] state3county5 Fifth county in third state

CHAR[4] state4county1 First county in fourth state

CHAR[4] state4county2 Second county in fourth state

CHAR[4] state4county3 Third county in fourth state

CHAR[4] state4county4 Fourth county in fourth state

CHAR[4] state4county5 Fifth county in fourth state

CHAR[24] descriptiveText Additional descriptive text

CHAR[5] producerCode Mapping center origin code

SHORT dataOrdering Direction of lines and samples

LONG numLines Number of lines (rows) in image

LONG numSamples Number of samples (columns) inimage

SHORT bandTypesAndOrder Number, types, and order of bands

SHORT elevationStorage Elevation storage code

SHORT bandAndElevationStorage Method of elevation storage

SHORT verticalDatum Vertical datum used

SHORT primaryHorizDatum Primary horizontal datum

SHORT secondaryHorizDatum Secondary horizontal datum

DOUBLE rotationAngle Orthophoto rotation WRT primarydatum

SHORT groundXYRefSystem Geographic, UTM or State Plane

SHORT groundXYZone Zone number if UTM or State Plane

SHORT groundXYUnits Map units

DOUBLE[2] SWPrimaryGroundCoord Map coords of SW primary quadcorner

DOUBLE[2] NWPrimaryGroundCoord Map coords of NW primary quadcorner

DOUBLE[2] NEPrimaryGroundCoord Map coords of NE primary quadcorner


102


DOUBLE[2] SEPrimaryGroundCoord Map coords of SE primary quadcorner

DOUBLE[6] primaryCoeff Primary transform coefficients

DOUBLE[2] primaryCentroid X and Y primary centroid

DOUBLE[2] SWSecondaryGroundCoord Map coords of SW secondary quadcorner

DOUBLE[2] NWSecondaryGroundCoord Map coords of NW secondary quadcorner

DOUBLE[2] NESecondaryGroundCoord Map coords of NE secondary quadcorner

DOUBLE[2] SESecondaryGroundCoord Map coords of SE secondary quadcorner

DOUBLE[6] secondaryCoeff Secondary transform coefficients

DOUBLE[2] secondaryCentroid X and Y secondary centroid

LONG[2] SWPrimaryInternalCoord File coords of SW primary quadcorner

LONG[2] NWPrimaryInternalCoord File coords of NW primary quadcorner

LONG[2] NEPrimaryInternalCoord File coords of NE primary quadcorner

LONG[2] SEPrimaryInternalCoord File coords of SE primary quadcorner

LONG[2] SWSecondaryInternalCoord File coords of SW secondary quadcorner

LONG[2] NWSecondaryInternalCoord File coords of NW secondary quadcorner

LONG[2] NESecondaryInternalCoord File coords of NE secondary quadcorner

LONG[2] SESecondaryInternalCoord File coords of SE secondary quadcorner

DOUBLE[2] firstPixelPrimary Primary map coords of (1,1) file pixel

DOUBLE[2] firstPixelSecondary Secondary map coords of (1,1) filepixel


103


SHORT elevationUnits DEM elevation units

FLOAT minElevation Minimum DEM elevation

FLOAT maxElevation Maximum DEM elevation

FLOAT groundResolutionX Ground X resolution of DEM

FLOAT groundResolutionY Ground Y resolution of DEM

FLOAT groundResolutionZ Ground Z resolution of DEM

FLOAT pixelResolutionX X resolution of orthophoto

FLOAT pixelResolutionY Y resolution of orthophoto

FLOAT pixelResolutionZ Z resolution of orthophoto

LONG largestPrimaryContourInterval Largest interval if DEM derived fromgraphic

SHORT largestPrimaryContourIntervalUnits

Units of Largest interval

LONG smallestPrimaryContourInterval Smallest interval if DEM derived fromgraphic

SHORT smallestPrimaryContourIntervalUnits

Units of Smallest interval

SHORT suspectAndVoidAreas Suspect and void areas in elevationor orthophoto data

FLOAT horizDoqAccuracy RMSE of image control points for X-Y

FLOAT verticalDoqAccuracy RMSE of primary DEM used

SHORT numDoqHorizTestPoints Number of DOQ horizontal test points

SHORT pixelProcessingAlgorithm Resampling method

CHAR[25] productionSystem Description of hardware & softwareused

TIME productionDate Production date

CHAR[25] filmType Manufacturer and ID of film type

CHAR[25] sourcePhotoID Descrip. of photo, agency, roll #, etc.

SHORT mosaickedImage Number of chips composing image


104


ENUM leafOff Leaves off treesFALSE or TRUE

TIME sourcePhotoDate Date of source photo

FLOAT focalLength Calibrated camera focal length in mm

LONG sourcePhotoFlyingHeight Nominal flying height of photograph

CHAR[25] scannerType Scanner description

FLOAT[2] scanningResolution (x,y) Aperture resolution, microns

FLOAT[2] scannerSamplingResolution (x,y) Sampling resolution, microns

SHORT radiometricResolution 8 or 16 bits

FLOAT resampledResolution Resampled resolution


105


DTED Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from a DTED source. The fields are copied from the File Header (HDR), User Header(UHL), Data Set Identification (DSI), and Accuracy Description (ACC) records. The descriptionis preceded by the record indicator from which the field was derived. All strings are NULLterminated. The description column indicates the source of the information. It is assumed thatthe user has access to the DTED documentation.


CHAR[18] FileName HDR File name

TIME CreationDate HDR Creation date of tape

TIME ExpirationDate HDR Expiration date of tape

CHAR[4] SecurityCode UHL Security Code

CHAR[13] UHL_ReferenceNumber UHL Unique reference number

SHORT MultipleAccuracy UHL 0=Single, 1=Multiple

CHAR SecurityClassification DSI Security classification code

CHAR[28] SecurityHandlingDescription DSI Security handling description

CHAR[6] SeriesDesignator DSI DMA series designator

CHAR[16] DSI_ReferenceNumber DSI Unique reference number

SHORT DataEditionNumber DSI Data edition number

CHAR MatchMergeVersion DSI Match/Merge version

CHAR[5] MaintenanceDate DSI Maintenance date (YYMM)

CHAR[5] MatchMergeDate DSI Match/Merge date (YYMM)

CHAR[9] ProducerCode DSI Producer code

CHAR[10] ProductSpecStockNum DSI Product specification stock number

SHORT ProductSpecAmendmentNum DSI Product spec. amendment number

CHAR[5] ProductSpecDate DSI Product specification date (YYMM)

CHAR[4] VerticalDatum DSI Vertical datum

CHAR[6] HorizontalDatumCode DSI Horizontal datum code

CHAR[11] DigitizingCollectionSystem DSI Digitizing collection system

CHAR[5] CompilationDate DSI Compilation date (YYMM)

106


DOUBLE OriginLatitude DSI Latitude of data origin

DOUBLE OriginLongitude DSI Longitude of data origin

DOUBLE SWCornerLatitude DSI Latitude of SW corner of data

DOUBLE SWCornerLongitude DSI Longitude of SW corner of data

DOUBLE NWCornerLatitude DSI Latitude of NW corner of data

DOUBLE NWCornerLongitude DSI Longitude of NW corner of data

DOUBLE NECornerLatitude DSI Latitude of NE corner of data

DOUBLE NECornerLongitude DSI Longitude of NE corner of data

DOUBLE SECornerLatitude DSI Latitude of SE corner of data

DOUBLE SECornerLongitude DSI Longitude of SE corner of data

DOUBLE OrientationAngle DSI Clockwise orientation angle of datawith respect to true north

DOUBLE LatitudeInterval DSI Latitude interval in tenths ofseconds between rows of elevationvalues

DOUBLE LongitudeInterval DSI Longitude interval in tenths ofseconds between rows of elevationvalues

SHORT NumLatitudeLines DSI Number of latitude lines

SHORT NumLongitudeLines DSI Number of longitude lines

SHORT PartialCellIndicator DSI Partial Cell Indicator

SHORT AbsoluteHorizontalAccuracy ACC Absolute horizontal accuracy ofproduct

SHORT AbsoluteVerticalAccuracy ACC Absolute vertical accuracy ofproduct

SHORT PointToPointHorizAcc ACC Point-to-Point horizontal accuracyof product

SHORT PointToPointVertAcc ACC Point-to-Point vertical accuracy ofproduct


107


MSS Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from a MSS source. The fields are copied from the Tape Directory (TD), Header(HDR), and Annotation (ANT) records. The description is preceded by the record indicator fromwhich the field was derived. All strings are NULL terminated. The description column indicatesthe source of the information. It is assumed that the user has access to the MSS documentation.


CHAR MissionNum TD Byte 8

TIME TapeCreationDate TD Bytes 12-16

USHORT NumVolumes TD Byte 20

ENUM format TD Byte 31NONE, BIL, BIP or BSQ

USHORT RecordLength TD Bytes 32-33

ENUM SourceHDT TD Byte 34FALSE or TRUE

CHAR[19] SceneID TD Bytes 35-52

CHAR[8] WRSDesignator HDR Bytes 20-26

CHAR[4] SensorID HDR Bytes 37-39

USHORT OrbitNum HDR Bytes 47-48

USHORT[26] ActiveDetectorStatus HDR Bytes 49-521 = Detector is Active

USHORT ActiveDetectorCount HDR Byte 57

USHORT UncorrectedPixelsPerLine HDR Byte 58

USHORT WRSScanLineNum HDR Bytes 73-74

USHORT WRSPixelNum HDR Bytes 75-76

USHORT NumAnnotationRecords HDR Bytes 101-102

USHORT NumAncillaryRecords HDR Bytes 105-106

ENUM GeoCorrectionsApplied HDR Byte 107FALSE or TRUE

ENUM GeoCorrectionDataPresent HDR Byte 108FALSE or TRUE

108


ENUM RadiometricCorrectionsApplied HDR Byte 109FALSE or TRUE

ENUM RadiometricCorrectionDataPresent

HDR Byte 110FALSE or TRUE

ENUM ImageDataFormat HDR Byte 117UNKNOWN,UNFRAMED_RECTANGULAR_IMAGE,FRAMED_RECTANGULAR_IMAGE, orFRAMED_SQUARE_IMAGE

USHORT LineInterleavingCount HDR Byte 121

USHORT BitsPerPixel HDR Byte 122

ENUM ResamplingApplied HDR Byte 123NONE,CUBIC_CONVOLUTION orNEAREST_NEIGHBOR

SHORT WRSImageCenterOffset HDR Byte 125-126

USHORT PixelsPerScanLine HDR Byte 131-132

USHORT NumUsableImages HDR Byte 135

USHORT NumTrailerRecords HDR Byte 144-145

ENUM DayPass HDR Byte 151FALSE (Night pass) orTRUE (Day pass)

ENUM CalWedgeMode HDR Byte 162UNKNOWN,LOW_GAIN_LINEAR_TRANSMISSION,LOW_GAIN_COMPRESSED_TRANSMISSION,HIGH_GAIN_LINEAR_TRANSMISSION,HIGH_GAIN_COMPRESSED_TRANSMISSION

USHORT TempRegPt1CurImgScanLine HDR Bytes 183-184

USHORT TempRegPt1CurImgPixelNum HDR Bytes 185-186


109


USHORT TempRegPt1RefImgScanLine HDR Bytes 187-188

USHORT TempRegPt1RefImgPixelNum HDR Bytes 189-190













USHORT OverlapMark1ScanLine HDR Bytes 215-216

USHORT OverlapMark1PixelNum HDR Bytes 217-218







USHORT OverlapMarkPixelOffset HDR Byte 231

USHORT GeoModelQualityAssessment HDR Byte 232

USHORT NumTickMarksTop HDR Byte 233

USHORT NumTickMarksLeft HDR Byte 234

USHORT NumTickMarksRight HDR Byte 235


110


USHORT NumTickMarksBottom HDR Byte 236

ENUM EdipsContrastEnhancement HDR Byte 3583FALSE or TRUE

ENUM EdipsAtmScatterCompensation HDR Byte 3584FALSE or TRUE

ENUM EdipsEdgeEnhancement HDR Byte 3585FALSE or TRUE

USHORT[8] DataPresentByBand HDR Byte 35861 = Data Present

FLOAT FormatCenterLatitude ANT Bytes 17-22

FLOAT FormatCenterLongitude ANT Bytes 24-31

CHAR[10] NominalPathRowID ANT Bytes 32-40

FLOAT NominalLatitude ANT Bytes 43-48

FLOAT NominalLongitude ANT Bytes 50-57

CHAR[8] SpectralBandIDCode ANT Bytes 58-64

ENUM TransmissionType ANT Byte 66UNKNOWN, DIRECT orSTORED_PLAYBACK

CHAR[15] SunAngles ANT Bytes 68-81

ENUM CorrectionType ANT Byte 82NONE,SYSTEM_CORRECTION,GEOMETRIC_GCP_CORRECTION, orRELATIVE_GCP_CORRECTION

CHAR[16] ImageScale ANT Byte 83“185 km x 185 km”,“ 99 km x 99 km”, or“185 km x 170 km”


111


TickMark Structure

Eixm_Mss-MapProjection

MapProjection ANT Byte 84NONE, UTM,POLAR_STEREOGRAPHIC,HOTINE_OBLIQUE_MERCATOR,SPACE_OBLIQUE_MERCATOR, orLAMBERT

ENUM EphemerisType ANT Byte 87UNKNOWN,PREDICTIVE, orDEFINITIVE

ENUM ProcessingProcedure ANT Byte 89UNKNOWN, ABNORMAL, orNORMAL

ENUM SensorGain ANT Byte 91UNKNOWN, HIGH_GAIN orLOW_GAIN

CHAR[14] AgencyProject ANT Bytes 94-106

CHAR[16] FrameID ANT Bytes 107-121

structTickMark[16]

TopTickMark ANT Bytes 405-548See TickMark Structure table below.

structTickMark[25]

LeftTickMark ANT Bytes 803-964See TickMark Structure table below.

structTickMark[25]

RightTickMark ANT Bytes 1201-1263See TickMark Structure table below.

structTickMark[16]

BottomTickMark ANT Bytes 1599-1760See TickMark Structure table below.


USHORT position Number of pixels from top or left side

CHAR[8] label Tick Mark Label


112


SPOT Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from a SPOT source. The fields are copied from the SPOT Level 1A, 1B, and 2headers, SPOTVIEW/GEOSPOT (GIS) headers, and the Canadian SPOT (RADARSAT)headers. If the value is a string, it is left unchanged. If the value is a number, it is converted fromASCII to binary. The description column indicates the source of the information. It is assumedthat the user has access to the various SPOT documentation.

MAX_INT: Maximum integer. It is the default uninitialized value for certain fields.

MAX_DBL: Maximum double. It is the default uninitialized value for certain fields.

SP: SPOT Level 1A, 1B, and 2.

SV: SPOTVIEW 1.5 (GIS format).

GS: GEOSPOT 4.0 (GIS format).1

CS: Canadian SPOT.2

1. GIS-GEOSPOT Format Reference Manual2. Canadian SPOT documentation (RADARSAT).

✚ The Canadian SPOT header fields are not completely defined in this document. This will becompleted in a future edition of On-Line Help.

113


struct SpotHeader


CHAR[15] scnname SP: based on Fields 13 and 14 of file 2 record1.SV: This field is empty.GS: This field is empty.CS:

DOUBLE scncenlat SP: Field 13 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE scncenlon SP: Field 14 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE scncor1lat SP: Field 17 of file 2 record 2.SV: This field is 0.0.GS: tag NW_LAT in REP header file.CS:

DOUBLE scncor1lon SP: Field 18 of file 2 record 2.SV: This field is 0.0.GS: tag NW_LON in REP header file.CS:

DOUBLE scncor2lat SP: Field 21 of file 2 record 2.SV: This field is 0.0.GS: tag SW_LAT in REP header file.CS:

DOUBLE scncor2lon SP: Field 22 of file 2 record 2.SV: This field is 0.0.GS: tag SW_LON in REP header file.CS:

DOUBLE scncor3lat SP: Field 25 of file 2 record 2.SV: This field is 0.0.GS: tag NE_LAT in REP header file.CS:

DOUBLE scncor3lon SP: Field 26 of file 2 record 2.SV: This field is 0.0.GS: tag NE_LON in REP header file.CS:

114


DOUBLE scncor4lat SP: Field 29 of file 2 record 2.SV: This field is 0.0.GS: tag SE_LAT in REP header file.CS:

DOUBLE scncor4lon SP: Field 30 of file 2 record 2.SV: This field is 0.0.GS: tag SE_LON in REP header file.CS:

LONG scncenline SP: Field 15 of file 2 record 2.SV: This field is 0.GS: This field is 0.0.CS:

LONG scncenpixel SP: Field 16 of file 2 record 2.SV: This field is 0.GS: This field is 0.0.CS:

LONG scncor1line SP: Field 19 of file 2 record 2.SV: This field is 0.GS: tag NW_Y_PIXEL in HDR header file.CS:

LONG scncor1pixel SP: Field 20 of file 2 record 2.SV: This field is 0.GS: tag NW_X_PIXEL in HDR header file.CS:

LONG scncor2line SP: Field 23 of file 2 record 2.SV: This field is 0.GS: tag SW_Y_PIXEL in HDR header file.CS:

LONG scncor2pixel SP: Field 24 of file 2 record 2.SV: This field is 0.GS: tag SW_X_PIXEL in HDR header file.CS:

LONG scncor3line SP: Field 27 of file 2 record 2.SV: This field is 0.GS: tag NE_Y_PIXEL in HDR header file.CS:


115


LONG scncor3pixel SP: Field 28 of file 2 record 2.SV: This field is 0.GS: tag NE_X_PIXEL in HDR header file.CS:

LONG scncor4line SP: Field 31 of file 2 record 2.SV: This field is 0.GS: tag SE_Y_PIXEL in HDR header file.CS:

LONG scncor4pixel SP: Field 32 of file 2 record 2.SV: This field is 0.GS: tag NE_X_PIXEL in HDR header file.CS:

DOUBLE scnorientangle SP: Field 35 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE angleofinc SP: Field 36 of file 2 record 2.a

SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE sunazimuth SP: Field 37 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE sunelevation SP: Field 38 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

CHAR[17] scncentime SP: Field 40 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

CHAR[4] sensorid SP: Field 42 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:


116


CHAR[3] specmode SP: Field 43 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

LONG revolutionnum SP: Field 44 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:

CHAR[2] playback SP: Field 47 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

CHAR[9] preprocesslevel SP: Field 55 of file 2 record 2.SV: tag PRE_PROCESS_LEVEL in HDRheader file or tag CORRECTION_LEVEL inHDR header file.GS: tag PRE_PROCESS_LEVEL in HDRheader file or tag CORRECTION_LEVEL inHDR header file.CS:

ENUM correction SP: based on Field 56 of file 2 record 2.SV: This field is EMSC_FALSE.GS: This field is EMSC_FALSE.CS:

LONG deconvolution SP: Field 57 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:

CHAR resampling SP: Field 58 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

LONG ulxmap SP: This field is 0.SV: tag ULXMAP from header file.GS: tag NW_X_COORD in REP header file.CS:


117


LONG ulymap SP: This field is 0.SV: tag ULYMAP from header file.GS: tag NW_Y_COORD in REP header file.CS:

LONG lrxmap SP: This field is 0.SV: tag LRXMAP from header file.GS: tag SE_X_COORD in REP header file.CS:

LONG lrymap SP: This field is 0.SV: tag LRYMAP from header file.GS: tag SE_Y_COORD in REP header file.CS:

LONG xpixelsize SP: Field 59 of file 2 record 2.SV: tag XDIM in HDR header file.GS: tag XDIM in HDR header file.CS:

LONG ypixelsize SP: Field 60 of file 2 record 2.SV: tag YDIM in HDR header file.GS: tag YDIM in HDR header file.CS:

DOUBLE mapxpixelsize SP: Field 63 of file 2 record 2.SV: tag XDIM from header file.GS: tag XDIM in HDR header file.CS: This field is 0.0.

DOUBLE mapypixelsize SP: Field 62 of file 2 record 2.SV: tag YDIM from header file.GS: tag YDIM in HDR header file.CS: This field is 0.0.

CHAR[32] mapprojid SP: Field 61 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

LONG numcols SP: Field 50 of file 2 record 2.SV: tag NCOLS from header file.GS: tag NCOLS in HDR header file.CS:


118


LONG numlines SP: Field 51 of file 2 record 2.SV: tag NROWS from header file.GS: tag NROWS in HDR header file.CS:

LONG numbands SP: Field 9 of file 3 record 1.SV: tag NBANDS from header file.GS: tag NBANDS in HDR header file.CS:

CHAR[4] interleave SP: Field 52 of file 2 record 2.SV: This field is empty.GS: tag LAYOUT in HDR header file.CS:

CHAR[33] cartcoord SP: Field 72 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

CHAR[16] suncal SP: Field 79 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

CHAR[8] mapunits SP: This field is empty.SV: tag MAPUNITS from header file.GS: tag MAPUNITS in HDR header file.CS:

CHAR[35] mapproj SP: This field is empty.SV: tag PROJECTION from header file.GS: tag PROJ_ID in REP header file.CS:

LONG utmzone SP: This field is empty.SV: tag UTM_ZONE from header file.GS: tag PROJ_ZONE in REP header file.CS:

LONG utmeast SP: This field is empty.SV: tag UL_UTMEAST from header file.GS: This field is MAX_INT.CS:


119


LONG utmnorth SP: This field is empty.SV: tag UL_UTMNORTH from header file.GS: This field is MAX_INT.CS:

LONG stplaneeast SP: This field is empty.SV: tag UL_STPLANE_EAST from headerfile.GS: This field is MAX_INT.CS:

LONG stplanenorth SP: This field is empty.SV: tag UL_STPLANE_NORTH from headerfile.GS: This field is MAX_INT.CS:

LONG stplanecode SP: This field is empty.SV: tag ST_PROJ_CODE from header file.GS: tag PROJ_ZONE in REP header file.CS:

CHAR[6] hdatum SP: This field is empty.SV: tag HORIZONTAL_DATUM or tagDATUM from header file.GS: tag HORIZ_DATUM in HDR header file.CS: This field is empty.

CHAR[4] rgborder SP: Defaults to “123”.SV: tag BAND_RGB from header file.GS: tag BAND_RBG in HDR header file.CS: Defaults to “123”.

LONG GRSk SP: Field 9 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:

LONG GRSj SP: Field 9 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:

DOUBLE satlongnadir SP: Field 34 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:


120


DOUBLE satlatnadir SP: Field 33 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

CHAR[17] missionid SP: Field 68 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

DOUBLE pointingmirror SP: Field 45 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

CHAR[7] telmode SP: Field 46 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

CHAR[6] satelliteid SP: Field 41 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

DOUBLE[9] xcoord SP: Field 9 of file 2 record 3b.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:

DOUBLE[9] ycoord SP: Field 9 of file 2 record 3b.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:

DOUBLE[9] zcoord SP: Field 9 of file 2 record 3b.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:

DOUBLE[9] xvelocityvector SP: Field 9 of file 2 record 3b.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:


121


DOUBLE[9] yvelocityvector SP: Field 9 of file 2 record 3b.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:

DOUBLE[9] zvelocityvector SP: Field 9 of file 2 record 3b.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:

LONG[9] julianday SP: Field 9 of file 2 record 3b.SV: These fields contain 0s.GS: These fields contain 0s.CS:

LONG[9] timeofday SP: Field 9 of file 2 record 3b.SV: This field contains 0s.GS:CS:

CHAR[27] scenecentertime SP: Field 12 of file 2 record 3.SV: This field is empty.GS: This field is empty.CS:

LONG[73] rawimageline SP: Field 14 of file 2 record 3b.SV: These fields contain 0s.GS: These fields contain 0s.CS:

LONG[73] yawspeed SP: Field 14 of file 2 record 3b.SV: These fields contain 0s.GS: These fields contain 0s.CS:

LONG[73] avgrollspeed SP: Field 14 of file 2 record 3b.SV: These fields contain 0s.GS: These fields contain 0s.CS:

LONG[73] avgpitchspeed SP: Field 14 of file 2 record 3b.SV: This field contains 0s.GS:CS:


122


DOUBLE[4] lookangles SP: Field 15-18 of file 2 record 3b.SV: This field contains 0.0s.GS:CS:

DOUBLE[4] polynomial1 SP: Field 20 of file 2 record 3b.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:





CHAR[17] level2quality SP: Field 77 of file 2 record 2.SV: This field is empty.GS: This field is emtpy.CS:

CHAR[17] dateofdarkcal SP: Field 78 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

LONG ephemerislength SP: Field 84 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:


123


LONG ephemerisnumber SP: Field 83 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:

LONG numberofgcps SP: Field 64 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:

CHAR[17] GRSdesignator SP: Field 66 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS:

CHAR[17] referencesensorid SP: Field 69 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS: This field is empty.

CHAR[17] referencespecmode SP: Field 70 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS: This field is empty.

CHAR[17] referenceprocesslevel SP: Field 71 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS: See field “preprocesslevel ”.

LONG numberlostlines SP: Field 74 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

LONG numberlostdetectors SP: Field 75 of file 2 record 2.SV: This field is 0.GS: This field is 0.CS:

CHAR[17] sceneidentification SP: Field 10 of file 2 record 2.SV: This field is empty.GS: This field is empty.CS: This field is empty.


124


a. First character of string is either ‘L’ or ‘R‘ depending on how satellite passed over scanned area (L =negative; R = positive)b. Refer to the SPOT Standard CCT Format Document

DOUBLE GRSlatdelta SP: Field 11 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE GRSlondelta SP: Field 12 of file 2 record 2.SV: This field is 0.0.GS: This field is 0.0.CS:

LONG gainnumber SP: Field 48 of file 2 record 2.SV: This field is 0.GS: This field is 0.0.CS:

DOUBLE xpixelsized See field “xpixelsize ”.

DOUBLE ypixelsized See field “ypixelsize ”.

DOUBLE urxmap SP: This field is 0.0.SV: This field is 0.0.GS: tag NE_X_COORD in REP header file.CS:

DOUBLE urymap SP: This field is 0.0.SV: This field is 0.0.GS: tag NE_Y_COORD in REP header file.CS:

DOUBLE llxmap SP: This field is 0.0.SV: This field is 0.0.GS: tag SW_X_COORD in REP header file.CS:

DOUBLE llymap SP: This field is 0.0.SV: This field is 0.0.GS: tag SW_Y_COORD in REP header file.CS:

CHAR * datum[] See field “hdatum ”.

struct GeoSpotHeader See GeoSpot Header Table below.

struct SpotCanHeader See Spot Canadian Header Table below.


125


GeoSpot Header Tablea


ENUM geospotformat SP: This field is EMSC_FALSE.SV: This field is EMSC_TRUE.GS: This field is EMSC_TRUE.CS: This field is EMSC_FALSE.

CHAR * geospotversion[] SP: This field is empty.SV: This field is “1.5”.GS: This field is empty.b

CS: This field is empty.

LONG bandrowbytes SP: This field is 0.0.SV: tag BANDROWBYTES in headerfile.GS: tag BANDROWBYTES in HDRheader file.CS: This field is 0.0.

CHAR byteorder SP: This field is empty.SV: tag BYTEORDER in header file.GS: tag BYTEORDER in HDR headerfile.CS: This field is empty.

LONG numbits SP: This field is 0.SV: tag NBITS in header file.GS: tag NBITS in HDR header file.CS: This field is 0.

CHAR * correction_level[] See field “preprocesslevel ”.

DOUBLE deltax_origin SP: This field is 0.0.SV: This field is -MAX_DBL.GS:CS: This field is 0.0.

DOUBLE deltay_origin SP: This field is 0.0.SV: This field is -MAX_DBL.GS:CS: This field is 0.0.

126


CHAR * contact_info[] SP: This field is empty.SV: This field is empty.GS: tag CONTACT_INFO in REPheader file.CS: This field is empty.

CHAR * easting_size_units SP: This field is empty.SV: This field is empty.GS: tag EASTING_SIZE argument 2 inREP header file.CS: This field is empty.

CHAR * northing_size_units SP: This field is empty.SV: This field is empty.GS: tag NORTHING_SIZE argument 2in REP header file.CS: This field is empty.

DOUBLE grid_declination SP: This field is 0.0.SV: This field is 0.0.GS: tag GRID_DECLINATION in REPheader file.CS: This field is 0.0.

CHAR * job_id[] SP: This field is empty.SV: This field is empty.GS: tag JOB_ID in REP header file.CS: This field is empty.

CHAR * location[] SP: This field is empty.SV: This field is empty.GS: tag LOCATION in REP header file.CS: This field is empty.

DOUBLE magnetic_declination SP: This field is 0.0.SV: This field is 0.0.GS: tag MAGNETIC_DECLINATION inREP header file.CS: This field is 0.0.

DOUBLE mag_decl_annual_chg SP: This field is 0.0.SV: This field is 0.0.GS: tag MAG_DECL_ANNUAL_CHG inREP header file.CS: This field is 0.0.


127


CHAR * mag_decl_date[] SP: This field is empty.SV: This field is empty.GS: tag MAG_DECL_DATE in REPheader file.CS: This field is empty.

CHAR * map_name[] SP: This field is empty.SV: This field is empty.GS: tag MAP_NAME in REP headerfile.CS: This field is empty.

CHAR * map_number[] SP: This field is empty.SV: This field is empty.GS:CS: This field is empty.

CHAR * meridian_name[] SP: This field is empty.SV: This field is empty.GS: tag MERIDIAN_NAME in REPheader file.CS: This field is empty.

DOUBLE meridian_origin SP: This field is 0.0.SV: This field is 0.0.GS: tag MERIDIAN_ORIGIN in REPheader file.CS: This field is 0.0.

DOUBLE origin_x_coord SP: This field is 0.0.SV: This field is 0.0.GS: tag ORIGIN_X_COORD in REPheader file.CS: This field is 0.0.

DOUBLE origin_y_coord SP: This field is 0.0.SV: This field is 0.0.GS: tag ORIGIN_Y_COORD in REPheader file.CS: This field is 0.0.

CHAR * production_date[] SP: This field empty.SV: This field is empty.GS: tag PRODUCTION_DATE in REPheader file.CS: This field is empty.


128


CHAR * product_id[] SP: This field empty.SV: This field is empty.GS: tag PRODUCT_ID in REP headerfile.CS: This field is empty.

CHAR * proj_code[] SP: This field empty.SV: This field is empty.GS: tag PROJ_CODE in REP headerfile.CS: This field is empty.

CHAR * proj_id[] SP: This field empty.SV: This field is empty.GS: tag PROJ_ID in REP header file.CS: This field is empty.

DOUBLE proj_lat_true_scale SP: This field is 0.0.SV: This field is 0.0.GS: tag PROJ_LAT_TRUE_SCALE inREP header file.CS: This field is 0.0.

DOUBLE proj_meridian SP: This field is 0.0.SV: This field is -MAX_DBL.GS: tag PROJ_MERIDIAN in REPheader file.CS: This field is 0.0.

DOUBLE proj_parallel SP: This field is 0.0.SV: This field is -MAX_DBL.GS: tag PROJ_PARALLEL in REPheader file.CS: This field is 0.0.

DOUBLE proj_scale_factor SP: This field is 0.0.SV: This field is 0.0.GS: tag PROJ_SCALE_FACTOR inREP header file.CS: This field is 0.0.

DOUBLE proj_std_parallel_I SP: This field is 0.0.SV: This field is -MAX_DBLGS: tag PROJ_STD_PARALLEL_I inREP header file.CS: This field is 0.0.


129


DOUBLE proj_std_parallel_II SP: This field is 0.0.SV: This field is -MAX_DBLGS: tag PROJ_STD_PARALLEL_II inREP header file.CS: This field is 0.0.

LONG proj_zone SP: This field is 0.SV: This field is 0.0.GS: tag PROJ_ZONE in REP headerfile.CS: This field is 0.

DOUBLE raster_x_origin SP: This field is 0.0.SV: This field is 0.0.GS: tag RASTER_X_ORIGIN in REPheader file.CS: This field is 0.0.

DOUBLE raster_x_size SP: This field is 0.0.SV: This field is 0.0.GS: tag RASTER_X_SIZE in REPheader file.CS: This field is 0.0.

DOUBLE raster_y_origin SP: This field is 0.0.SV: This field is 0.0.GS: tag RASTER_Y_ORIGIN in REPheader file.CS: This field is 0.0.

DOUBLE raster_y_size SP: This field is 0.0.SV: This field is 0.0.GS: tag RASTER_Y_SIZE in REPheader file.CS: This field is 0.0.

DOUBLE sheet_rect_elevation SP: This field is 0.0.SV: This field is empty.GS: tag SHEET_RECT_ELEVATION inREP header file.CS: This field is 0.0.


130


a. Compiled from SPOTVIEW 1.5 and GEOSPOT 4.0 documentation.b. If geospotversion is EMSC_TRUE, an empty field implies GEOSPOT version 4.0.

Spot Canadian Header Table

CHAR * sheet_rect_type[] SP: This field empty.SV: This field is empty.GS: tag SHEET_RECT_TYPE in REPheader file.CS: This field is empty.

DOUBLE spheroid_flat SP: This field is 0.0.SV: This field is 0.0.GS: tag SPHEROID_FLAT in REPheader file.CS: This field is 0.0.

DOUBLE spheroid_maj_axis SP: This field is 0.0.SV: This field is 0.0.GS: tag SPHEROID_MAJ_AXIS in REPheader file.CS: This field is 0.0.

DOUBLE spheroid_min_axis SP: This field is 0.0.SV: This field is 0.0.GS: tag SPHEROID_MIN_AXIS inREP header file.CS: This field is 0.0.

CHAR * spheroid_name[] SP: This field empty.SV: This field is empty.GS: tag SPHEROID_NAME in REPheader file.CS: This field is empty.


DOUBLE nom_interpixel_dist SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE mon_interline_dist SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:


131


DOUBLE image_skew SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE orbital_inclination SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE sat_ascending_node SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE sat_altitude SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE sat_ground_speed SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE satellite_heading SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE satellite_latitude SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE satellite_longitude SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE acrosstrackFOV SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:


132


DOUBLE semi_major_axis SP: This field is 0.0.SV: This field is 0.0.GS: This field is 0.0.CS:

DOUBLE[16]

bandgain SP: These fields contain 0.0s.SV: These fields contain 0.0s.GS: These fields contain 0.0s.CS:

ENUM LGSOWG SP: This field is EMSC_FALSE.SV: This field is EMSC_FALSE.GS: This field is EMSC_FALSE.CS: This field is EMSC_TRUE.


133


TM Header

The following table defines the contents of the record written to an IMAGINE .img file which hasbeen read from a Landsat source. The fields are copied from the TM Fast Format headers. If thevalue is a string it is left unchanged. If the value is a number it is converted from ASCII to binary.All strings are NULL terminated. The description column indicates the source of the information.The term FF indicates the EOSAT Fast Format Header, and the term SF indicates EOSATStandard Format Header, it is assumed that the user has access to the EOSAT documents.

SF: “Landsat Technical Working Group (LTWG)”

FF: “EOSAT Fast Format Document for TM Digital Products, Version B”


LONG imageheight FF: Field 61.SF: table 8 bytes237-244.

LONG imagewidth FF: Field 59.SF: table 8 bytes 281-288

LONG numbands FF: based on Fields 94 and 35.SF: table 5 bytes 1413-1428.

CHAR[13] eosatsceneid FF: “NO SCENEID”.SF: table 3 bytes 91-117

CHAR rev FF: Field 117.SF: blank.

CHAR[9] acqdate FF: Field 6.SF: blank.

CHAR[3] satellitenum FF: Field 8.SF: blank.

CHAR[5] instrumenttype FF: Field 10.SF: blank.

CHAR[12] productnum FF: Field 2.SF: blank.

CHAR[15] producttype FF: Field 12.SF: blank.

CHAR[11] productsize FF Field 14.SF: blank.

CHAR[77] mapsheetname FF: Field 15.SF: blank.

134


CHAR[4] interleaving FF: “BSQ”.SF: table 3 bytes 131-154.

CHAR[5] scenesize FF: blank.SF: based on table 3 bytes 118-130.

CHAR[21] earthellipsoid FF: Field 51.SF: blank.

LONG orbitalpath FF: Field 4.SF: table 5 bytes 165-180.

LONG orbitalrow FF: Field 4.SF: table 5 bytes 165-180.

CHAR[5] usgsprojection FF: Field 43.SF: table 5 bytes 1557-1572.

LONG usgsprojectionnum FF: Field 45.SF: 0.

LONG usgsmapzonenum FF: Field 47.SF: 0.

DOUBLE pixelsize FF: Field 56.SF: table 6 bytes 365-380.

DOUBLE[15] usgsprojparms FF: Field 49.SF: 0.0s.

DOUBLE upperleftlong FF: Field 63.SF: 0.0.

DOUBLE upperleftlat FF: Field 65.SF: 0.0.

DOUBLE upperlefteasting FF: Field 67.SF: calculated from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE upperleftnorthing FF: Field 69.SF: calculated from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE upperrightlong FF: Field 71.SF: 0.0.

DOUBLE upperrightlat FF: Field 73.SF: 0.0.


135


DOUBLE upperrighteasting FF: Field 75.SF: calculated from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE upperrightnorthing FF: Field 77.SF: calculated from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE lowerrightlong FF: Field 79.SF: 0.0.

DOUBLE lowerrightlat FF: Field 81.SF: 0.0.

DOUBLE lowerrighteasting FF: Field 83.SF: calculated from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE lowerrightnorthing FF: Field 85.SF: calculated from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE lowerleftlong FF: Field 87.SF: 0.0.

DOUBLE lowerleftlat FF: Field 89.SF: 0.0.

DOUBLE lowerlefteasting FF: Field 91.SF: calculate from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE lowerleftnorthing FF: Field 93.SF: calculated from table 5 bytes 85-100,101-106; pixelsize, scenesize.

DOUBLE scenecenterlat FF: Field 107.SF: 0.0.

DOUBLE scenecenterlong FF: Field 105.SF: 0.0.

LONG scenecenterline FF: Field 113.SF: table 5 bytes 85-100.

LONG scenecenterpixel FF: Field 112.SF: table 5 bytes 101-106.


136


DOUBLE scenecenternorthing FF: Field 111.SF: table 6 141-156.

DOUBLE scenecentereasting FF: Field 109.SF: table 6 bytes 157-172.

CHAR[11] geodproctype FF: Field 17.SF: blank.

CHAR[3] resampalgorithm FF: Field 19.SF: table 5 bytes 1541-1556.

DOUBLE semimajoraxis FF: Field 53.SF: 0.0.

DOUBLE semiminoraxis FF: Field 55.SF: 0.0.

DOUBLE radgainband1 FF: Field 21.SF: 0.0.







DOUBLE radbiasband1 FF: Field 21.SF: 0.0.





137





CHAR[17] wrsdesignator FF: blank.SF:

CHAR[17] wrscycle FF: blank.SF:

LONG sunelevation FF: Field 101

LONG sunazimuth FF: Field 103

DOUBLE orientationangle FF: Field 41

DOUBLE nominterlinedist FF: 0.0.SF: table 6 bytes 61-76.

DOUBLE nominterpixeldist FF: 0.0.SF: table 6 bytes 45-60.

DOUBLE nomaltitude FF: 0.0.SF: table 6 bytes 493-508.

DOUBLE nomgroundspeed FF: 0.0.SF: table 6 bytes 509-524.

DOUBLE crosstrackFOV FF: 0.0.SF: table 6 bytes 557-572.

DOUBLE displayrotangle FF: 0.0.SF: table 6 bytes 445-460.

DOUBLE scenecenterheading FF: 0.0.SF: bytes 525-540.

DOUBLE sensorscanrate FF: 0.0.SF: table 6 bytes 573-588.

DOUBLE sensorsamplerate FF: 0.0.SF: table 6 bytes 589-604.

DOUBLE nomorbitinclincation FF: 0.0.SF: 0.0.


138


CHAR[6] datum FF: blank.SF: blank.

LONG offset FF: Field 115.SF: 0.0.


139



The PDF below is one of the files supplied with IMAGINE. A few additional comments have beenadded for clarity. This file and others like it are found in <IMAGINE_HOME>/devices/printers and<IMAGINE_HOME>/defaults. They have the .pdf file extension.

/**************** Kodak XL7700 ********************************/

/*** Model -- Substitute Kodak XL7700 with the name of your printer.*/model(“Printer Model”): “Kodak XL7700”

“Printer manufacture and model”;

queuename(“Print Queue Name”): “xl7700”“Print queue name for printer”;

queuehost(“Print Queue Host”): expand “$HOSTNAME”“Host to which the printer is attached”;

device(“Device”): “/dev/sip0”“Device name of printer”;

systemfive(“Print Queue Type”) : “BSD”“Queue host use system V or BSD print daemon?”enums {

“BSD” “BSD type of printing, lpr” “SYSTEM V” “SYSTEM V type of printing, lp”

};/*** Color. Mapmaker creates 3 layers for RGB, 4 layers for CMYK, and 1 layer** for Black. The first line is default. Enums includes other options.*/color(“Color Options”): “RGB” “Printer color paths”

enums { “RGB” “Red Green Blue” “Black” “Black Only”

};

/*** Density.*/density(“Transparent Density”): “Normal”

“Output transparent density”enums {

“Normal” “Normal density”“High” “High density”“Low” “Low density”

};

140


/*** size - You can set other min, max values here to minimize mistakes.*/mediawidth(“Media Width”) : 8.5

“The given media width”min 0;

mediaheight(“Media Height”) : 11 “The given media height”min 0;

/*** Type.*/unittype(“Media Units”) : “inch”

“Unit Type”enums {

“inch” “English system” “meter” “Metric system” “centimeter” “Metric system” “millimeter” “Metric system”

};

densitywidth(“Horizontal Dot Density”) :203“Dots per unit horizontal (e.g. DPI)”min 0;

densityheight(“Vertical Dot Density”) :203“Dots per unit vertical (e.g. DPI)”min 0;

/*** Type.*/dotsunittype(“Dot Units”) : “inch”

“Printer Density Unit Type”enums {

“inch” “English system” “meter” “Metric system” “centimeter” “Metric system” “millimeter” “Metric system”

};

/*** Put the correct min, max here to minimize user error.** Use 0 for unlimited, e.g. set totalpixelheight to 0 for roll paper.*/totalpixelwidth(“Total Horizontal Pixels”) :2048

“Total number of pixels horizontal (e.g. DPI)”min 0;

141


totalpixelheight(“Total Vertical Pixels”) :1536“Total number of pixels vertical (e.g. DPI)”min 0;

mirror(“Use a Mirrored Image”) : “false”“Is the image mirrored?”boolean “true” “false”;

/*** Number of copies.*/numcopies(“Number of Copies”) : 1

“Number of copies to print”min 1max 1000;

/*** Color intensity level for each layer. For example, a dye-sub has 256 for** each layer, an electrostatic plotter only has 1.*/intenselevel(“Color Intensity Level”) : 256

“The printer color intensity level (max 256)”min 256max 256;

142

Installing, Compiling, and Running the Example Files


If you are setting up the toolkit for UNIX, see Under UNIX .

Under Microsoft Windows

Installation

The IMAGINE Toolkit for Windows 98/NT installer is a single executable file. When the installeris run it creates a directory called “toolkit” in the IMAGINE install directory. This directorycontains library files, C header files, and a set of programming examples to demonstrate the useof the toolkit. Help files are also installed into the IMAGINE help directory.

Requirements

The IMAGINE Toolkit for Windows 98/NT was created for use with the Microsoft Visual C++development environment version 5.0. Programs created with the toolkit that utilize EML willrequire an installed and licensed version of IMAGINE to operate.

Using the Example Projects

In the $IMAGINE_HOME/toolkit/examples directory there is a Microsoft Visual C++ workspacefile called “examples.dsw” which can be used to load all of the example projects. The workspacehandles the dependency of each project upon the ewin_main project, ensuring that theewin_main library is compiled and available for linking with the examples.

Each example project creates the executable in the $IMAGINE_HOME/bin/NTx86 directory.After they are compiled they can be run from the IMAGINE commands window. This window isaccessed with the Commands... item in the Session menu on the IMAGINE toolbar. Many ofthe examples require command line options as explained in the sources and some depend uponexample data in the $IMAGINE_HOME/examples directory.

Compatibility Limitations

These examples and most of IMAGINE itself are based upon common source shared betweenthe UNIX and Windows 95/NT environments. To achieve this the use of the ANSI C libraries andWin32 libraries has been avoided whenever possible (except for the math libraries). There aremany packages in the elib library that were created to support this with the foremost being efio,estr, and emsc.

✚ Note that when specifying explicit pathnames under Windows, you must place quotes aroundthe pathname and you must use forward slashes (/) when running examples from the SessionCommand History dialog.

143


Structure Packing

The IMAGINE Toolkit libraries have been compiled using the /Zp4 compiler option. This placesstructure members on 4 byte boundaries. The default for the Microsoft compiler is /Zp8. Thisoption is necessary because of the way in which the emif toolkit package interprets the datadictionaries in HFA files.

To understand why, you have to understand what the packing is all about. For reasons ofperformace, some systems impose memory alignment requirements on primitive data types. Forexample, longs may be required to begin on a 4 byte boundary and doubles may be required tobegin on an 8 byte boundary. When we say that address “a” is on an n byte boundary we meanthat “a mod n” is 0. In C a structure member is an offset that begins from the base address ofthe structure. To say that a structure member is aligned to a given bounday means that its offsetis so aligned.

The Microsoft compiler has an option (/Zpn) that provides control over the alignment of structuremembers. It chooses the smaller alignment of the argument (n) and the native aligment of thedatatype. So, for example, if /Zp4 is used and a double is placed in a structure this double will bealigned on a 4 byte boundary instead of the native 8 byte boundary because 4 is smaller than 8.While the /Zpn option controls the alignment of structure members, it does not control thealignment of data in memory. This causes emif a problem because it is based on the assumptionthat data and structure members are subject to the same alignment rules. The Microsoft compilerappears to use 4 byte alignment rules for data in memory, so the /Zp4 option makes the data andstructure member alignment work for emif.

For users of the toolkit (elib, emllib, etc.) this means that they must insure that IMAGINEstructures are compiled with 4 byte alignment. This can be done in several ways. The source filecan be compiled with /Zp4, or the includes for the IMAGINE headers can be bracketed with thepragmas which guarantee the 4 byte alignment. An example of this is below:

/*** Force the aligment for the imagine includes to 4.*/#pragma pack(push, imagine_pack, 4)/*** Include the imagine include files.*/#include <emsc.h>#include <emif.h> :#include <eimg.h>/*** Return the packing to whatever it was.*/#pragma pack(pop, imagine_pack)

144


Under UNIX

The IMAGINE Developers’ Toolkit for UNIX comes with a shell script which will create asubdirectory in your home directory containing example source code along with makefiles. Thiswill allow a beginning Toolkit programmer to have some working examples to begin modifyingand experimenting with. To invoke this script, give the following command:

<IMAGINE_HOME>/install/setup_toolkit

where <IMAGINE_HOME> is the directory where IMAGINE was installed.

This will create the directory $HOME/imaginetk<version> (where <version> is a three digitnumber representing the version of IMAGINE - e.g. 831 or 840) and copy several source filesand a makefile into it. Now make the example files with the following command:

cd $HOME/imaginetk<version>make all

☞ Be sure to use the version of make that came with your system, and not a variant such asGNU make.

145

Example File Descriptions


This list summarizes the C Programmer’s Toolkit example files. For more detailed information,click the file name. Also, remember to examine the source code for additional comments.

♦ read80descrip — reads and prints the descriptors (statistics, contrast table, color tables,etc.). of an IMAGINE image file (demonstrates reading and manipulating IMAGINE descriptortables)

♦ copy80layer — copies a selected layer of an IMAGINE image file to a very simple rasterformat (demonstrates reading and manipulating IMAGINE raster data)

♦ RasterAccess —prints the pixel value for selected image layer, row, and column(demonstrates accessing individual pixels in IMAGINE raster layers)

♦ subset1 — opens an IMAGINE image file and writes a subset of the image into an output file(demonstrates the argument parsing package)

♦ subset2 — similar to subset1, but includes full error checking and reporting (demonstratesthe error reporting package)

♦ subset3 — adds the session manager and a graphical user interface to subset2(demonstrates the session manager and progress meter packages, and writing graphicalfront ends to IMAGINE functions)

♦ eemlsample — explains how to write a simple GUI application using the EML toolkit. Use theMakefile.example to compile the program. This sample application demonstrates the use ofsimple EML API functions. For a more complete example see table program.

♦ readmssephemeris — reads the ephemeris (sensor) data structure from an IMAGINE fileimported from a LANDSAT MSS (Multispectral Scanner) tape. The data is read into a Cstructure, and selected members of the structure are printed to standard output.

♦ degrad — degrades an input raster image to get a lower resolution output.

♦ digview — digitize image points from viewer.

♦ eprj_sample — demonstrates how to write a program that IMAGINE can use to perform yourown map projection. Because it communicates with IMAGINE via pipes, it cannot be runstand-alone.

♦ fonttablemaker — creates a map composition that is a table of ASCII values and associatedcharacters (demonstrates writing annotation layers).

146


♦ table — explains how to write a complex GUI application using the EML toolkit. Use theMakefile.example to compile the program. For a simple example see eemlsample program.

♦ importex — demonstrates import functions available in eixlib by creating a simple importerwhich reads ERDAS 7.5 LAN files.

♦ exportex — demonstrates export functions available in eixlib by creating a simple exporterwhich writes ERDAS 7.5 LAN files.

♦ chartdemo — demonstrates the functionality of the Eeml_Chart and CellArray packages.

♦ fxgeneral — illustrates most of the major points of reading and writing an ERDAS IMAGINE.img file.

The IMAGINE libraries look for a series of environment variables which are normally defined bythe ‘imagine’ startup script.

Under UNIX, these programs can be run stand-alone. Use the script called ‘runex’ (run example)which sets the needed environment variables and then runs the specified program. For example,to run the eemlsample program type runex eemlsample .

147


Example: read80descrip.c

The file read80descrip.c shows how to access descriptor data from an IMAGINE image file. Thisexample and the two that follow, copy80layer.c and RasterAccess.c, are good examples tofollow if you primarily want to access IMAGINE data for use in other programs. Using theseexamples as guides, you can also write programs to export IMAGINE files into any desired fileformat.

Due to the convention used to name Toolkit functions and data structures, the Toolkit Includefiles needed are very easy to identify. All functions in the eimg package, for example, aredeclared in the file eimg.h. In addition to the four packages discussed above, the header fileemsc.h is included as well. This file contains a series of useful macros and enumerated datatypes. For example, the enumerated type Emsc_Boolean provides a standard method ofrepresenting boolean (true/false) data as either EMSC_TRUE or EMSC_FALSE. There are alsodefinitions for EMSC_MIN and EMSC_MAX, the minimum and maximum of two numbers, andEMSC_PI, among others.

read80descrip.c declares two global variables,

static EintToolkitData *erdinit = NULL;

which is necessary for all toolkit programs, and

static Eerr_ErrorReportingMode reportingmode = EERR_DEBUG;

which states that error reports will list each function in the calling sequence, rather than just thetop-level function call. In order to focus on the capabilities of the eimg package, most of the errorchecking and reporting available through eerr has been omitted. (It will therefore be easy tocrash!) The reportingmode variable is included in case you want to extend the error reporting.

After initializing the toolkit, the program finds the names of the layers of the input file viaeimg_LayerGetNames . This function returns a pointer to an Estr_StringList structure, whichcontains an array of character strings along with the value count containing the number ofstrings in the array. The layer names are used in the function eimg_LayerOpen , which opensa single layer. Each layer in the input file is opened as read-only by includingEIMG_LAYER_OPTION_READONLY in the variable argument list.

The pixels of a raster layer are partitioned into rectangular blocks, with all blocks having the samewidth and height (in pixels). Pixels are read from or written to the layer through theeimg_LayerRead or eimg_LayerWrite functions. A partial listing of the Eimg_layer structure isshown below:

typedef struct EIMG_LAYER { long width; /* Width (in pixels) of the layer */ long height; /* Height (in pixels) of the layer */ Eimg_LayerType layerType; /* Type of this layer (e.g., thematic) */ Egda_PixelType pixelType; /* Type of pixels in this layer (e.g., unsigned

148


8-bit) */ long blockWidth; /* Width (in pixels) of each block in the layer */ long blockHeight; /* Height (in pixels) of each block in the layer

(in pixels) *//* Other structure elements */

} Eimg_Layer;

The layer width, height, type (thematic or continuous) and pixeltype are easily accessed onceeimg_LayerOpen is called.

The eimg package contains a number of high-level function calls for reading and writingdescriptor data. In read80descrip.c , each type of descriptor data is accessed similarly. First,a pointer to the appropriate descriptor table is declared and initialized to NULL. Next, a functionof the form eimg_XXXXRead is called (i.e. eimg_StatisticsRead , eimg_HistogramRead ,eimg_ColorTableRead , eimg_ClassNamesRead , eimg_MapInfoRead , andeimg_ProParametersRead ). The second argument of each function is a pointer to the type ofdescriptor to be returned. If this argument is NULL, then a descriptor table of the proper type isallocated within the function if the descriptor exists. If the second argument is not NULL, thefunction assumes that the table has already been created, with the second argument pointing toit. In this program, we are only accessing each descriptor table once, so in each case NULL ispassed as the second argument.

If the descriptor table does not exist in the layer, the returned pointer is NULL. Otherwise, thedata in the table is printed to standard output, and the table is deallocated. The Esta_Statistics,Esta_Histogram, Esta_ColorTable, Esta_ClassNames, Eprj_MapInfo and Eprj_ProParametersstructures are shown in the documentation under the esta and eprj packages.

149


Example: copy80layer.c

The next example, copy80layer.c, shows how to access raster data in IMAGINE files. Thisprogram copies a selected raster layer from an IMAGINE file to a simple raster file format. As inthe previous example, the idea is to show how to access IMAGINE data rather than to create atruly useful application. As before, the program begins by initializing the Toolkit, and finding thelayer names of the input file. Next, the desired layer is opened and the layer width and height arequeried.

☞ Note that a file containing n layers has layers indexed from 0 to n-1. The IMAGINE userinterface must be designed to handle the discrepancy between “layer number” and “layerindex” by subtracting one from the user’s input before it is passed to the application.

IMAGINE raster data is stored in a Eimg_PixelRect structure. The Eimg_PixelRect structure isthe same as the Egda_BaseData structure, shown below:

typedef struct { long numrows; long numcolumns; Egda_PixelType datatype; Egda_ObjectType objecttype; Egda_Byte *data; /* pointer to the data array */ Egda_Byte *currentData; /* can be set to point to anywhere within data

array */ long pitch; /* Number of bytes between rows */ Emsc_Boolean derivedFlag; /* indicate data array is derived or not */ long numelements; /* total elements in data array */ long numbytes; /* number of bytes per-pixel */ Emsc_Opaque *userdata; /* user specified data pointer */} Egda_BaseData;

The Eimg_PixelRect buffer is allocated using the function eimg_PixelRectCreate , whichrequires the number of rows and columns and the data type as arguments. In this example, thedata type for the buffer, and hence the output file, is that of the input layer. The layer informationis read into the buffer with the function eimg_LayerRead .

An output file is created, and the number of rows and columns in the image are written as longintegers to the beginning of the file as a simple header. Since the raster data for the layer isstored contiguously beginning at pixelblock->data , it may be written to the output file with asingle fwrite function.

The output file may be examined using the View Binary Data... option from the Tools menu.Open the file and set the Data Type to match the source file.

150


Example: RasterAccess.c

RasterAccess.c demonstrates how to access individual pixels in an IMAGINE file. The programprompts the user for the layer number and the column and row within the layer, and returns thepixel value. Unlike copy80layer.c, we don’t want to be limited to a single layer. To manage morethan one layer within a file, the Toolkit provides a datatype, Eimg_LayerStack, which is simply acollection of related layers. The calling syntax for the function eimg_LayerStackOpen is verysimilar to eimg_LayerOpen. Since only one pixel is read at a time, an Eimg_PixelRect is createdwhich holds only one pixel. It is created with a floating point data type (EGDA_TYPE_F32), soall data types (except complex) may be read.

After the layer, column and row are entered by the user, the appropriate pixel is read into theEimg_PixelRect variable using eimg_LayerRead. Note that opening a layerstack opens each ofthe layers in the layerstack, so operations may be performed on each layer individually as wellas on the layerstack as a whole. The pointer to an individual pixel in a pixelrect may be foundusing the macro EIMG_DATAPTR, which takes as arguments a pointer to the pixelrect, and thecolumn and row of the pixel. The macro is defined in eimg.h as

#define EIMG_DATAPTR(RECT,COLUMN,ROW) /(((RECT)->currentData) + (ROW)*((RECT)->pitch) + (COLUMN)*((RECT)->numbytes))

Since the pixelrect contains only one pixel, the column and row values for the pixelrect are bothzero. The macro returns an Egda_Byte pointer, and must be cast to the data type of the pixelrect,in this case 32-bit floating point (Egda_F32).

This program is run from the Session Command History dialog with the following syntax:

rasteraccess “<filepath>” <layer_number> <column_number> <row_number>

Results are returned to the Session Log window.

For example, rasteraccess “C:/imagine/examples/lanier.img” 2 90 40 returns the value 23. Thiscan be verified by opening the file in a viewer and using the inquire cursor to view pixel values.Be sure to set File cordinates before entering 90 in the X cell and 40 in the Y cell. Then read thepixel value for the layer of interest under the FILE PIXEL column.

An alternate method of accessing pixels is to read the entire raster contents of a file into anEimg_PixelRectStack object, and then access pixels one at a time from the pixelrectstack. Thefollowing code fragment illustrates the technique. It requires much more memory since the entireimage is read, and there may be a delay while the data is read, depending on the size of theimage.

Eimg_LayerStack *inlayerstack; Eimg_PixelRectStack *pixelrectstack; Eimg_PixelRect *pixelrect; Egda_F32 *pixelptr;

151


...

/*** Allocate space for the pixel to be read*/ pixelrectstack = eimg_PixelRectStackCreate (nlayers, ncols, nrows, EGDA_TYPE_F32,&errorreport);

/*** Read the layerstack into the pixelrectstack*/ eimg_LayerStackRead(inlayerstack, 0, 0, ncols, nrows, pixelrectstack, &errorreport);

/*** Get the layer, column and row value from the user** and read the appropriate pixel value. Keep looping** until user enters a value of -1*/ while (1) {

printf (“Enter layer, column, row: “);scanf (“%d %d %d”, &layer, &column, &row);if (layer != -1) { pixelrect = pixelrectstack->datalayer[layer]; pixelptr = (Egda_F32 *) (EIMG_DATAPTR (pixelrect, column, row)); printf (“Pixel value = %g\n”, *pixelptr);}else break;

}/*** Deallocate pixel storage*/ eimg_PixelRectStackDelete (pixelrectstack, &errorreport);

/*** Close the input layerstack*/ eimg_LayerStackClose (inlayerstack, &errorreport);

152


Example: display_anno.c

This example shows how to open and display an annotation layer (.ovr file). The accompanyingEML script provides the canvas for display.

153


Example: draw_demo.c

The draw_demo example is intended to show how the different draw modes can affect thedisplay of various objects in a canvas. It makes use of a dialog to select draw mode, object., andobject color. The result is displayed on a canvas containing red, green, and blue rectangles inthe dialog.

It also shows an example of using ButtonDown events to gather coordinate information andreturning this info via a Message Dialog.

154


Example: convolve.c

This example program performs a convolution on the specified IMAGINE file (.img) using thespecified kernel. The result is written to the specified output file. Optional command-linearguments include meter which displays a job progress meter while the program is running andboundaryvalue which sets the value for pixels outside the image or specified window.

The optional window specification allows you to extract and process a subset of the originalimage.

The calling syntax is:

convolve <infile> <outfile> -k <X_size> <Y_size> <k 1,1 > ... <k X_size,Y_size >

Where X_size and Y_size define the size of the filter kernel and kx,y are the coefficients of thefilter kernel matrix. Optional arguments are described in the source file, convolve.c.

155


Example: canvas_test.c

This is a demonstration of how to display various kinds of objects on a canvas. The types ofobjects are hard coded and some parameters are pseudo-randomly generated. Each time thecanvas is refreshed, much of it changes due to the random nature.

156


Example: subset1.c

The subset1.c example program demonstrates the use of the argument parsing package. Thisprogram writes a rectangular subset of an image, specified by the file coordinates of the upper-left and lower-right corners of the rectangle, to a new file.


subset1 <inputfile> <outputfile> <ulx> <uly> <lrx> <lry>

For example, under Windows:subset1 “C:/temp/lanier.img” “C:/temp/lanier_AirPort.img” 178 340 257 404

creates the new image file lanier_AirPort.img containing only the region of the air port.

The Earg_Cmd array is specified as

static Earg_Cmd format[] ={subset_subset, “subset1 %s %s %d %d %d %d”, ““, EARG_NO_ERR,EARG_END};

This specifies that the name of the program, subset1, must be followed by two string argumentsand four integer arguments. These six arguments are passed to the function subset_subset viathe *argv array. Since there are no optional arguments, any deviation from this calling syntaxreturns an error.

Function main merely initializes the Toolkit and parses the command line with the functionearg_DoArgs . earg_DoArgs checks the calling syntax and then calls the subset_subset routine,which is where the real work of the program is done. If there is an error in the call to earg_DoArgs,such as incorrect command line syntax, errorreport returns a non-NULL value, causing theEerr_ErrorReport structure to be printed and then deleted before exiting the program.

The subset_subset function first finds the names of the layers of the input file viaeimg_LayerGetNames . Next, the corner points of the subsetted image are converted fromargument-string form to long ints, and width and height of the subsetted image are found.

Each layer in the input file is then opened as read-only, and the output layer is given a namewhich is similar to the input layer name. For example, if the input file layer name is“mobbay.img(:Layer_1)” and the output file name is “mobbay_subset.img”, then the output filelayer name is “mobbay_subset.img(:Layer_1)”. Once the output layer name is derived, theoutput layer is created using the function eimg_LayerCreate. This function has a variable-lengthargument list which allows various characteristics and properties of the layer to be defined. Inthis case, the option EIMG_LAYER_COMPUTE_STATS_ON_CLOSE is enabled, which, as itsname indicates, instructs the layer to compute it statistics when the layer is closed.

157


Next, the data buffer pixelblock is allocated using eimg_PixelRectCreate , and is made to be thesame size as the subset. The data is read from the input layer into the buffer, and then written tothe output layer using eimg_LayerRead and eimg_LayerWrite . Both the input and output layersare closed, with statistics calculated on the output layer, and the data buffer is deallocated.

158


Example: subset2.c

Example subset2.c example program builds on subset1.c by adding full error-checking, andby adding an optional argument to the command line. The data type of the output file may nowbe chosen using the -p option. Note that a new function, set_pixeltype, has been added, and anew entry describing the calling syntax for the -p option is added to the Earg_Cmd structure. Inaddition, two new global variables, logpixeltypeset and pixeltypeout, have been added.logpixeltypeset is a boolean variable which, when true, indicates that a non-default value is to beused for the output pixeltype. The pixeltypeout variable stores the output pixeltype. Oneconsequence of the command format structure in the earg package is that functions called byearg_DoArgs must use global variables to communicate with one another. Since the number ofcommand-line options is fairly small for most programs, this is not a major limitation.


subset1 <inputfile> <outputfile> <ulx> <uly> <lrx> <lry> -p <data type>

For example, under Windows:subset2 “C:/temp/lanier.img” “C:/temp/lanier_AirPort.img” 178 340 257 404 -p s16

creates the new image file lanier_AirPort.img as in the previous example but changing the datatype from unsigned 8-bit to signed 16-bit..

Error Reporting

The other major addition in subset2.c is complete error reporting. As stated earlier, it’s a goodidea to check the returning error pointer after each call to a toolkit function, and subset2 does justthat. Since much of the code pertaining to error reporting is similar, two macros, ErrorCreate andErrorExit, are included to reduce typing and improve readability. The macros may be used if thefollowing conditions hold: the error is considered “Fatal,” the error string is a constant, there is astring variable named functionname which contains the name of the current function, and thepointer to the error reporting structure is called errorreport. The ErrorExit macro is used when noadditional cleanup, such as freeing allocated memory, needs to be done before exiting. If suchcleanup does need to be done, the ErrorCreate macro may be called, which simply calls theeerr_CreateErrorReport function, and the subsequent printing of the error message, cleanup,and exiting must be performed “by hand.” In some cases, such as if the error message is notconstant, the macros are not used.

159


Example: subset3.c

The next example uses an EML script that sets up a graphical user interface to the subsettingprogram.

This program is run from a DOS command window with the following syntax:

<install drive>:\<imagine home>\bin\ntx86\eml subset3.eml

For example:

D:\imagine\bin\ntx86\eml subset3.eml

To open the dialog under UNIX, type the command

<IMAGINE_HOME>/bin/ arch /eml subset3.eml

where arch is one of sun4, decux, sgi, hp700, rs6000 or aviion.

First, examine the subset3.c example program. It allows the program to connect to the IMAGINESession Manager, producing a small dialog which tracks the progress of the program, andprovides a Cancel button allowing the user to interrupt the process at any time. This is exactlywhat happens during resampling, importing/exporting, running the modeler, etc. The functionspertaining to the Session Manager are in the esmg (Session Manager) and emet (ProgressMeter) packages. In order to use the Progress Meter, you must declare a global pointer to anEmet_MeterInfo structure. In function main, call the function esmg_JobInit , which connects theprogram to the session manager if it is running. The meter information structure is initializedinside the function set_meter, which is called only if the command line contains the -m[eter]option.

The progress meter functions used in subset3.c are:

♦ emet_MeterInfoChangeTaskName

♦ emet_MeterInfoPrint

♦ emet_MeterInfoSet

160


The function emet_MeterInfoChangeTaskName is used to print a string representing the currentstatus of the operation to the progress box. emet_MeterInfoPrint sets the percentage completionof the operation. If there are several subtasks involved in the operation, emet_MeterInfoSetmakes reporting of the correct percentage easier. emet_MeterInfoSet maps the 0-100%completion range of a subtask to a smaller range. For example, suppose there are four layers inan image. The processing of each layer should advance the progress meter 25%. Usingemet_MeterInfoSet, the progress of each layer may be reported from 0% to 100%, but theprogress meter will advance from 0% to 25% for the first layer, 25% to 50% for the second layer,etc. Using the layer option EIMG_LAYER_OPTION_PROGRESS_METER_ON_CLOSE, theprogress meter may be instructed to advance during any operations which are performed whena layer is closed, such as computing statistics. In the subset_subset function, half of the progressfor each layer is set aside for copying the image block, and half for computing statistics of thenewly-created layer. Note that the reading and writing of raster data is done one line at a time inthis example rather than in a single block. This makes the motion of the progress metersmoother, since it is updated after each line.

EML Scripts

The Session Manager and Progress Meter functions are not useful unless the application iscalled from an EML (ERDAS Macro Language) script. As stated earlier, EML provides aconvenient method of producing easy-to-use graphical user interfaces (GUIs). With a littlepractice, even complex dialog may be produced without undue effort. Two items are necessaryto produce a graphical user interface using EML: the EML interpreter and an EML script. An EMLscript provides a description of the various dialogs and menus of an interface, and the interpreterproduces the interface from the description. The interpreter itself is simply called eml, andresides in the directory <IMAGINE_HOME>/bin/arch, where arch is one of sun4, decux, sgi,hp700, rs6000 or aviion.

EML uses a syntax similar to the C language. Each dialog or window on the screen produced byEML is called a frame . The various buttons, menus, etc. with which the user interacts are calledframeparts . Groups of related frames (all of the frames used for one application, for example)are known as components . All frames must reside inside a component.

The subset3.eml example script describes the user interface for the subset3 program. Since thefunctionality of the program is simple and straightforward, only one frame is needed. Afterdeclaring a component called subset3, the frame subsetdialog is declared within the subset3component. The title keyword describes what appears on the top bar of the dialog, and the atkeyword governs the position of the dialog with respect to the upper left corner of the screen.Next, any frameparts which are referred to before they are defined must be declared.

161


The subsetdialog frame contains five frameparts: a group containing two filename frameparts,corresponding to the input and output filenames, a popuplist which determines the pixel type ofthe output image, a group containing four textnumber frameparts which control the corner pointsof the subsetted image, and two buttons labelled Cancel and OK. Each framepart has a name,similar to a variable name, and a value, which is generally set by the user. Each framepart alsocontains a generic description (title, location, size), and other framepart-specific attributes. Aframepart position may be described relative to a previously defined framepart. Finally, mostframeparts contain one or more event handlers which describe the effect of the framepart.

The subset3 program (created by subset3.c ) is invoked by clicking on the OK button. The jobkeyword is used here, which begins an application as a background process. If the applicationconnects itself to the Session Manager, then a progress meter appears.

Event Handlers

An event handler describes which user actions are important to the dialog and what steps to takewhen such user actions are triggered. An event handler consists of the on keyword followed byone of the standard Event Messages and an action to take. Different frameparts have differenttypes of event handlers.

For example, the only event handler which may be used with a button framepart is ONMOUSEDOWN, which is triggered whenever the button is clicked. A textnumber framepart, onthe other hand, contains the event handlers ON INPUT, which is triggered when a user enters anumber, and ON VALUECHANGED, which is initiated when the value of the textnumberframepart changes. Note that components and frames may also contain event handlers, whichare typically used to set initial conditions. In subset3.eml , the component event handler ONSTARTUP is used, which instructs the eml interpreter to display the subsetdialog frameimmediately after parsing the EML script. The frame event handler ON FRAMEDISPLAY may beused to initialize variables in a frame; it is not used in this example, however.

162


Example: readmssephemeris.c

The program readmssephemeris.c shows how to read ephemeris or header data informationfrom IMAGINE files. Many IMAGINE raster importers, in particular LANDSAT TM and MSS,SPOT, and AVHRR, transfer the ephemeris data from the source image into the IMAGINE file.This example shows how to read the ephemeris data into a C structure from a file imported froman MSS tape. All that is necessary is to declare a pointer to an Eixm_MssHeader structure(defined in Eixm_Mss.h), initialize the toolkit package, and then call eixm_MssHeaderRead. Thereturn value points to the filled-in C structure containing the ephemeris data values. Once theephemeris data is loaded into the C structure, several of the fields are then printed to standardoutput. The sample file mssdata.img containing an MSS ephemeris data node is in the examplesdirectory. Once the program is compiled, it may be run by typing

readmssephemeris <IMAGINE_HOME>/examples/mssdata.img

163


Example: degrad.c

The program degrad.c can be used to degrade an input raster image to get a lower resolutionoutput by using the average of original pixel values instead of by resampling the original data.Such a degradation has been proved to be appropriate for layered correlation matchingprocesses.

degrad “<inputname>” “<outputname>” [<meter> ] [<size> ] [<exclude> ]

inputname → %s

Name of input file.

outputname → %s

Name of output file.

meter → -m[ eter ]

Display progress meter during execution.

size → -s [ ize ] xsize ysize → -s [ ize ] %d %d

Specify size in x and y direction for degrade. The default is 2 in both directions.

If the input file size is ncolumns by nrows, the output file will be:ncolumns / xsize by nrows / ysize

exclude → -e [ xclude ] excludevalue → -e [ xclude ] %f

Set value to exclude in computing statistics in the output file.

This program, once compiled and linked, may be run by itself (see command-line syntax above)or it can be invoked through EML to open a dialog.

To open the dialog, run this program from a DOS command window with the following syntax:

<install drive>:\<imagine home>\bin\ntx86\eml degrad.eml

For example:

D:\imagine\bin\ntx86\eml degrad.eml

To open the dialog under UNIX, type the command

<IMAGINE_HOME>/bin/ arch /eml degrad.eml

where arch is one of sun4, decux, sgi, hp700, rs6000 or aviion.

164


Example: digview.c

The program digview.c can be used to digitize image points from a viewer. In order to be able tocommunicate with a viewer, “digview” must be run under the same session as the viewer.

The program digviewpt.c contains the actual digitizing subroutine that is called by digview.c.

These examples show you how to establish connection with viewer, how to create and update acellarray, how to digitize points from a viewer, and how to display points in a viewer.

The user interface code related to this example can be found in digviewpt.eml. Digitized pointscan be moved within the viewer or selected and deleted from the cellarray.

165


Example: eprj_sample.c

The program eprj_sample.c is an example of an executable that IMAGINE can use to performmap projection calculations external to IMAGINE. The file eprj_sample.c shows the functionsthat you must provide to do the actual calculations. Your functions must be named exactly asthey are named in eprj_sample.c, but you may name your executable whatever you like. Youmust link your functions with the eprj_ExternalMain.o provided in <IMAGINE_HOME>/usr/lib/<arch>. This is the engine that communicates with IMAGINE and calls your functions. You mustthen add your projection to the end of the <IMAGINE_HOME>/etc/mapprojections.dat file. Asample mapprojections.dat file is provided in the imaginetk820 directory created in your homedirectory when you ran setup_toolkit. Your executable and the modified mapprojections.dat file(usually located in <IMAGINE_HOME>/etc) must be located on the path defined byEPRJ_PROJECTIONS_PATH in <IMAGINE_HOME>/bin/imagine_environment.

166


Example: fonttablemaker.c

The program fonttablemaker can be used to create a two-page map composition that is a tableof ASCII values and their associated characters. It demonstrates creating an IMAGINEannotation layer and creating most of the various kinds of annotation elements and annotationstyles, as well as creating a simple map composition.

After making the fonttablemaker application it can be run under IMAGINE by running IMAGINEfrom the directory where fonttablemaker was built and accessing fonttablemaker through theexisting menu item in the Utilities Menu of the IMAGINE icon panel. This source and script forfonttablemaker are the same as those used for the fonttablemaker application that is distributedas part of IMAGINE.

Under UNIX, it can be run stand-alone as follows:

$IMAGINE_HOME/examples/runex fonttablemaker [-b[lob]]

where

-b[lob] will create at the upper-left corner of the map composition an example annotation groupof various annotation elements of various annotation styles

When you run fonttablemaker you will be presented with a dialog from which you can specify themap composition name, the size of one page of the map and the font for which you want the tablegenerated.

167


Example: eemlsample.c

This program eemlsample.c, demonstrates how to write a GUI application using the EML APItoolkit. It uses the eemlsample.eml (an EML script) to build its GUI. The API calls used in thisexample are sufficient enough to write a GUI application, however, to get more in-depth detail onavailable API functions see the table program.

To understand this application you do not need any prior knowledge/experience in writing GUIapplications. However, having such experience will be very useful for understanding the EMLAPI toolkit.


eempsample

There are no arguments.

Under Unix it can be run with the runex script (found in $IMAGINE_HOME/examples directory)as follows or it can be run under IMAGINE by adding it to the icon panel by modifying a local copyof imagine.eml.

$IMAGINE_HOME/examples/runex eemlsample

168


Example: table.c

This program table.c, demonstrates how to write a GUI application using the EML API toolkit. Ituses the table.eml (an EML script) to build its GUI. The API calls used in this example aresufficient enough to write a complete and complex GUI application. If you have troubleunderstanding this application see the simple GUI application - eemlsample .

To understand this application you need to have some knowledge of EML API toolkit and how tocreate custom EML parts etc. Before you begin see the simple example mentioned above(eemlsample program) to familiarize yourself with the EML Toolkit.

This table program demonstrates not only the EML API functions but also the interaction of a Cprogram with an EML script. Examples here will show how to provide a callable function definedin your C program for use in an EML script. These are called application functions in EML. It willalso show how to install one of the custom EML parts (CellArray) in an EML script and it providesexamples to create all the data types supported by the CellArray and explains how to use manyof the CellArray access API functions. You will also learn how to create a Document fame,menubar, statusbar, toolbar etc. as described in the EML Reference Manual .


table

There are no arguments.

Under UNIX it can be run with the runex script (found in $IMAGINE_HOME/examples directory)as follows or it can be run under IMAGINE by adding it to the icon panel by modifying a local copyof imagine.eml.

$IMAGINE_HOME/examples/runex table

169


Example: importex.c

The importex.c program is an example of an IMAGINE importer. Although it doesn’t contain anEML front end or have preview capabilities, it does support all other options that are normallyfound in IMAGINE importers, such as subsetting by band and area, and selection of output pixeltype, block size, compression type, etc. The input and output files and other options are specifiedvia an Earg_Cmd structure, with exactly the same format as is found in the IMAGINE importers.A typical command line would be something like

importex -in “C:/usr/data/myimage.lan” -out “C:/usr/data/myimage.img” -meter “pct”

The functions eixm_SetBands, eixm_SetBlocksize, etc. specified in the Earg_Cmd structureautomatically set the fields in the global Eixm_Options structure eopt. In addition to containingprogram options specified on the command line, the Eixm_Options structure also contains manyother useful fields pertaining to the input and output files which are derived later.

The LAN header is read by defining a 128-byte structure which corresponds exactly to the LANheader structure. See ERDAS Ver. 7.X File Formats for header structure details.The headercan then be read in using a single efio_ReadSeq function call. However, since the LAN file formatis based on a least-significant byte (LSB) architecture, we must perform a byte swap on anymultibyte fields in the structure.

In the ImportData function, additional options structure fields are populated based on values inthe LAN header, and the band and geographic subsetting is set up. After the output layerstackis created, the characteristics of the input data structure are specified in the Eixm_Descripstructure. This is similar in some ways to the Eixm_Options structure, but contains only itemswhich describe the input data. Here we have decided to import data in 64-pixel-high strips. Next,eixm_ImportInit is called to initialize low-level buffers which are used during subsequent calls toeixm_LayerStackImport. The eixm_LayerStackImport function does all of the work, once theEixm_Descrip structure has been set up and eixm_ImportInit has been called.

170


Example: exportex.c

The exportex.c program is an example of an IMAGINE exporter. Like importex.c, it doesn’tcontain an EML front end, but is included to demonstrate that raster data may be easilytransferred via the eixm toolkit package. Much of the discussion for importex.c applies toexportex.c as well.


exportex -in imgfile -out lanfile -meter pct

If the output file already exists, it will not be overwriten.

171


Example: chartdemo.c

The chartdemo program demonstrates how to use the Eeml_Chart package for graphicallydisplaying data in an XY line graph as well as displaying it in a CellArray. The CellArray can beedited and the results are immediately displayed in the Chart.


chartdemo

172


Example: fxgeneral.c

While the Developers’ Toolkit On-Line Help provides a description of each function in eachpackage the best way to learn is by example. This example program illustrates most of the majorpoints of reading and writing an ERDAS IMAGINE .img file.

The following sections illustrate the steps in creating an ERDAS IMAGINE file. These are drawnfrom the fxgeneral.c example.

Also included in the examples directory is a sample ERDAS IMAGINE image file for this program.It is a small subset of a Landsat Thematic Mapper scene named small_tm.img.


fxgeneral small_tm.img stretch.img

This command will stretch the layers of the input file and write the results to the output file. It willalso create a TM Header node in the output file.

Initialize the Toolkit

Before any functions in the IMAGINE Developers’ Toolkit can be called, the toolkit must beinitialized. The value returned must be passed to many of the toolkit functions so it should be keptin a global variable.

/*

** Initialize the ERDAS toolkit

*/

eInit = eint_InitToolkit( (Emsc_Opaque**)&err );

SHOW_ERROR( return ( 1 ) );

Determine the Layers

Most applications will operate on each of the layers in the toolkit. This can be done sequentiallyor in parallel. In either case the list of names of image layers must be known before processingbegins. The following illustrates how to get names of the layers.

/*

** Determine the names of all the layers in the input file

*/

layerNames = eimg_LayerGetNames( inputFile, eInit, &err );

173


The return is a pointer to an Estr_StringList. This is a structure which contains a count and anarray of pointers to chars. Each pointer points to the name of a layer. This structure mustultimately be freed by the application using a call to estr_StringListDelete.

Open the Input Layer

The input layer name is contained in the Estr_StringList./*

** Open up the input layer

*/

inLayer = eimg_LayerOpen( inLayerName, eint_GetInit(), &err,

EIMG_LAYER_OPTION_READONLY,

EIMG_LAYER_OPTION_END );

Create the Output Layer

In this case the output layer name is constructed from the input layer name plus the output filename.

/*

** Determine this input layer EHFA node name

*/

eimg_LayerNameParse( layerNames->strings[layer],

NULL, NULL, &inLayerNode, &err );

SET_ERROR( __LINE__, “eimg_LayerNameParse failed”, break );

/*

** Form the output layer name

*/

outLayerName = eimg_LayerNameCreate( outDir, outBase,

inLayerNode, &err );

/*

** Create the output layer

** The compute stats option will compute statistics andhistogram

** for the layer when the layer is closed.

*/

outLayer =

eimg_LayerCreate( outLayerName, inLayer->layerType, p, w, h,

174


eint_GetInit(), &err,

EIMG_LAYER_OPTION_COMPUTE_STATS_ON_CLOSE,

EIMG_LAYER_OPTION_END );

Allocate Pixel Array

Data is read from and written to an Eimg_PixelRect. The PixelRect is a structure which definesa rectangular array of pixels. The pixel may be any of the 13 types of data supported by ERDASIMAGINE. The types are:

The following example uses a double precision floating point type since all of the integer andfloating point types can be handled this way. The read and write functions will automatically castthe data to the type of the PixelRect.

Name Description

EGDA_TYPE_U1 Single bit data. In memory there is one significant bit perpixel (byte). In the file it is packed 8 pixels to a byte.

EGDA_TYPE_U2 Two bit data. In memory there are two significant bits perpixel (byte). In the file it is packed 4 pixels to a byte.

EGDA_TYPE_U4 Four bit data. In memory there are four significant bitsper pixel (byte). In the file it is packed two pixels to abyte.

EGDA_TYPE_U8 8 bit unsigned data. There is one pixel per byte.

EGDA_TYPE_S8 8 bit signed data. There is one pixel per byte.

EGDA_TYPE_U16 16 bit unsigned data. There are two bytes per pixel.

EGDA_TYPE_S16 16 bit signed data. There are two bytes per pixel.

EGDA_TYPE_U32 32 bit unsigned data. There are four bytes per pixel.

EGDA_TYPE_S32 32 bit signed data. There are four bytes per pixel.

EGDA_TYPE_F32 32 bit floating point data (single precision). There arefour bytes per pixel.

EGDA_TYPE_F64 64 bit floating point data (double precision). There are 8bytes per pixel.

EGDA_TYPE_C64 64 bit complex data. There are two 32 bit floats per pixel,the real and imaginary parts.

EGDA_TYPE_C128 128 bit complex data. There are two 64 bit floats perpixel, the real and imaginary parts.

175


/*

** Create a buffer to contain a block of pixels from the inputlayer

** We declare the pixels to be double precision floating point

** numbers. eimg_LayerRead will automatically convert the input

** for us.

*/

pixels = eimg_PixelRectCreate( inLayer->blockWidth,

inLayer->blockHeight, EGDA_TYPE_F64,

&err );

SET_ERROR( __LINE__, “eimg_PixelRectCreate failed”, gotocleanup );

Read Data

Data is read from an ERDAS IMAGINE layer as a rectangular region. If one wished to read asingle line, then a wide rectangle of height one would be read. If the data type of the file isdifferent from the data type of the PixelRect then the data will be converted on the fly.

/*

** Read this block from the input file

*/

eimg_LayerRead( inLayer, column, row, bWidth, bHeight,

pixels, &err );

Modify the Data

The PixelRect contains a pointer called currentData. This is a void pointer which points to thebeginning of the data in memory. There is another member in the structure called pitch whichrepresents the number of bytes from the start of one row to the next. This should be usedbecause it is not guaranteed that each row is an even number of data type units wide.

/*

** Rescale data values

*/

for ( j = 0; j < bHeight; j++)

{

rowJcolumn = (double*)(pixels->currentData+j*pixels->pitch);

for ( i = 0; i < bWidth; i++ )

176


{

rowJcolumn[i] *= mult;

rowJcolumn[i] += add;

}

}

Write the Data

As with reading, the data is written to the file as a rectangular subset. This subset may be anysize and may begin at any point in the file. If the data in the PixelRect is of a different type thanthat of the file then it is converted on the fly. The conversion from a larger type to a smaller is asimple truncation against the limits of the type. For example if 4096.345 is written to an unsigned8-bit file then the output pixel is 255.

/*

** Write this block to the output file

*/

eimg_LayerWrite( outLayer, column, row, bWidth, bHeight,

pixels, &err );

Close the Layers

The layers must be closed when processing is complete. Closing the output file will cause allnecessary support information to be written to the file. In addition it will compute the statistics forthe layer if that option was set.

/*

** Close the input layer (if opened)

*/

if ( inLayer != (Eimg_Layer*)NULL ) eimg_LayerClose( inLayer,&err );

SHOW_ERROR( ; );

/*

** Close the output layer (if created)

*/

if ( outLayer != (Eimg_Layer*)NULL ) eimg_LayerClose( outLayer,&err );

SHOW_ERROR( ; );

/*

** Delete the pixel storage

177


*/

eimg_PixelRectDelete( pixels, &err );

Create the Design For the Special Object

Before writing an object such as the TM Header to a file, a design must be created. This is anexample of creating a design for the TM Header in an IMAGINE file. The information about theheader can be found in the HFA Object Directory chapter.

design = emif_DesignCreate( NULL, “TMHeader”, &err,

EMIF_T_LONG, “imageheight”,

EMIF_T_LONG, “imagewidth”,

EMIF_T_LONG, “numbands”,

EMIF_T_CHAR|EMIF_M_ARRAY,“eosatsceneid”,13,

:

EMIF_T_LONG, “offset”,

EMIF_T_END );

Write the Object to the File

This example will write a node to the file which contains an object called “TM_Header.” The typeof the object is “TMHeader.” When the file is closed its dictionary will contain the definition of theTMHeader type.

/*

** Copy the design to the data dictionary of the output file

*/

emif_AddDesignToDictionary( oFile->dictionary,TMHeaderDesign, &err );

SET_ERROR( __LINE__, “emif_AddDesignToDictionary fail”, gotocleanup );

/*

** Write the TM Header data object to the file

*/

ehfa_ObjectWrite( oFile, EHFA_ROOT_NODE, “TM_Header”,“TMHeader”,

EHFA_WRITE_FIRST_CHILD, TMHeader_Data(),

TMHeaderDesign, &err );

178


Example: imagecopy.c

This is a very straight-forward example in which all raster layers are copied from one file toanother. This program is run from the Session Command History dialog with the following syntax:

imagecopy <inputfile> <outputfile>

ERDAS - Developers Toolkit Examples on-LineManual'

Documents

Transcript of ERDAS - Developers Toolkit Examples on-LineManual'