ImageVision Library™ Programming Guide Document Number 007-1387-050 CONTRIBUTORS Written by George Eckel, Jackie Neider, and Eleanor Bassler Illustrated by Seth Katz, Nancy Cam, Bill Pickering, and Eleanor Bassler Edited by Nan Schweiger Engineering contributions by Chris Walker, Nancy Cam, Venkatesh Narayanan, Dan Baca, Jon Brandt, Don Hatch, and Casey Leedom Photography by Jackie Neider, Jim Winget, Nancy Cam, and Judith Quenvold Cover St. Peter’s Basilica image courtesy of ENEL SpA and InfoByte SpA. Disk Thrower image courtesy of Xavier Berenguer, Animatica. © 1993, 1995, 1996, Silicon Graphics, Inc.— All Rights Reserved The contents of this document may not be copied or duplicated in any form, in whole or in part, without the prior written permission of Silicon Graphics, Inc. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure of the technical data contained in this document by the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/or in similar or successor clauses in the FAR, or in the DOD or NASA FAR Supplement. Unpublished rights reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94043-1389. Silicon Graphics and IRIS are registered trademarks and IRIS-4D, IRIX, IRIS Graphics Library, IRIS IM, ImageVision, ImageVision Library, and RealityEngine are trademarks of Silicon Graphics, Inc. Motif is a trademark of Open Software Foundation. UNIX is a registered trademark of UNIX System Laboratories. X Window System is a trademark of the Massachusetts Institute of Technology. Microsoft is a registered trademark of Microsoft Corporation. Apple and Macintosh are registered trademarks of Apple Computer, Inc. Kodak and Kodak Photo CD are trademarks of Eastman Kodak Company. Red-tailed boa photograph property of Judith Quenvold. ImageVision Library™ Programming Guide Document Number 007-1387-050 Contents List of Figures xiii List of Tables xvii List of Examples xix About This Guide xxi What This Guide Contains xxi Suggestions for Further Reading xxiii Adding a User Interface to Your ImageVision Library Program xxv Style Conventions xxvi 1. Writing an ImageVision Library Program 1 A Sample Program in C++ 2 C++ Version of the Sample Program 3 More about the Sample Program 4 The C Interface 9 Creating and Deleting C++-style Objects 9 Calling Functions 10 Including Header Files 11 A Sample Program in C 11 2. The ImageVision Library Foundation 15 The IL Class Hierarchy 15 Foundation Classes 16 The ilLink Class 17 The ilImage Class 19 iii Contents Image Attributes 20 Error Codes 22 Size 22 Data Type 23 Data Ordering 24 Color Model 25 Determining Operator Data Types, Ordering, Working Types, and Definable Fields 26 Color Palette 27 Orientation 28 Fill Value 29 Minimum and Maximum Pixel Values 30 Data Compression 32 The Cache 32 Managing Cache 35 Priority 36 Page Size 38 Multi-threaded Paging Support 39 Accessing Image Data 40 Two-dimensional Functions 40 Three-dimensional Functions 46 Data Access Support Functions 47 Orientation Support 48 Geometric Mapping Support 49 The IL Execution Model 50 On-demand Processing 50 Multi-threading 53 Using Graphics Hardware for Acceleration 55 Working with Image Chains 56 Dynamically Reconfiguring a Chain 57 Propagating Image Attributes 59 Object Properties 61 iv Contents 3. Accessing External Image Data 65 Supported IFL Image File Formats 66 FIT 66 GIF 66 JFIF (JPEG) 67 ilTCL 67 Kodak Photo CD Image Pac 67 Kodak Photo CD Overview Pac 69 PNG 69 PPM/PGM/PBM 69 Raw 69 SGI 70 TIFF 70 YUV 71 Alias 71 SOFTIMAGE 71 Using IL to Access an Image 71 Opening an Existing File 71 Creating an Image File 73 Setting a File’s Compression 75 Querying a File Image 76 Setting and Getting Special Image Properties 77 Importing and Exporting Image Data 78 Images in Memory 78 v Contents 4. Operating on an Image 81 Image Processing Operators Provided with IL 84 Color Conversion and Transformation 85 Arithmetic and Logical Transformations 90 Geometric Transformations 98 Spatial Domain Transformations 106 Edge Detection 117 Frequency Domain Transformations 120 Generation of Statistical Data 132 Radiometric Transformations 136 Combining Images 146 Constant-valued Images 152 Using a Null Operator 152 Defining a Region of Interest 153 Creating an ilRoiImg 154 Creating an ilSubImg 156 5. Displaying an Image 159 Overview of the Display Facility 160 Scrolling Windows 164 A Simple Interactive Display Program 165 Sample Program Code 165 Sample Program Comments 167 Creating an ilDisplay 169 Opening an X Window and Creating an ilDisplay Object 169 Adding a View to the ilDisplay Object 170 Deallocating the Display 171 Choosing OpenGL or X Rendering 171 vi Contents View and Display Basics 171 Background Color 172 Borders 172 Preventing View Operations 174 Deferring Drawing 174 The Drawing Area 175 Managing the Cache 175 Mode Flags 175 Managing Views 177 Adding Images 177 Stereo Viewing 178 Retrieving Views 179 Retrieving Images 179 Removing Views 180 Replacing Images 180 Reordering the View Stack 180 Finding a View 181 Finding an Edge 181 Operating on a Pixel 182 Locating a Point 183 Applying a Display Operator 184 Drawing Views 184 Relocating Views and Images 188 Resizing Views 193 Updating Views 195 Using setMouse() 196 A More Complicated Interactive Display Program 196 6. Extending ImageVision Library 199 Deriving From ilImage 202 Data Access Functions 203 Color Conversion 207 Managing Image Attributes 207 Deriving From ilCacheImg 212 vii Contents Deriving From ilMemCacheImg 213 Implementing an Image Processing Operator 215 Deriving From ilOpImg 217 Handling Image Processing 221 Deriving From ilMonadicImg or ilPolyadicImg 228 Deriving From ilSpatialImg 234 Deriving New Classes From ilWarpImg and ilWarp 237 Deriving From ilFMonadicImg or ilFDyadicImg 238 Deriving From ilFFiltImg 241 Deriving From ilRoi 242 Using an ROI: The ilRoiIter class 243 Deriving New Classes From ilRoi 243 Deriving New Classes From ilRoiIter 243 7. Optimizing Your Application 247 Managing Memory Usage 247 Optimizing Use of Cache 247 Page Size 251 Buffer Space 253 Using Hardware Acceleration 253 Using Accelerated Operators 253 Understanding the OpenGL Imaging Pipeline 255 Composing Operators 256 Pixel Buffers and Multi-Pass Acceleration 258 Texture 259 Texture Allocation 266 Hardware-Specific Acceleration Restrictions 266 General Restrictions 266 InfiniteReality 267 Reality Engine 267 Impact/High Impact 268 Indy/Indigo2 268 viii Contents Hardware Hints 268 Using IL-Recognized Hints 269 Creating Your Own Hints 271 8. The Programming Environment 273 Compiling and Linking an IL Program 273 Programs Written in C++ 273 Programs Written in C 275 Reading the Reference Pages 275 Image Tools 277 Online Source Code 277 Environment Variables 278 Caching Configuration Issues 280 Hardware-Acceleration Configuration Issues 280 Hardware Display Configuration Issues 280 Monitoring Control Issues 281 Multi-Threading Configuration Issues 283 A. What is New in Version 3.1 285 keepPrecision() Added to ilOpImg 285 Multiprocessing on Single CPU Machines Enabled 285 Additional Image Formats Supported 285 ELT Performance Enhanced 286 Choosing OpenGL or X Rendering 286 API Change for ilImgStat 286 B. What is New in Version 3.0 287 Overview of Changes in 3.0 287 Understanding the New Features 288 Support for OpenGL and Hardware Acceleration 288 64-bit Address Space Support 289 Understanding New Classes 289 ix Contents Understanding the Changes to the Existing Features 292 Multi-threading Architecture Changes 292 Asynchronous Operations 292 Changes to the Display Facility 294 Error handling 295 Polynomial Coordinate Structures 296 Run-time Object-Type Query Macros 297 Changes to Existing Classes 298 Backwards Compatibility with IL 2.5 306 Automatic Class Name Conversion 308 New Derivations for Classes 313 C. Introduction to C++ 315 Objects and Classes 315 Overloaded Functions 316 Inheritance 317 Public versus Protected versus Private 318 Passing by Reference 318 Default Values 318 Class Declaration Format 319 Linking with Libraries in Other Languages 319 Referring to Function Names 321 D. Summary of All Classes 323 E. Implementing Your Own Image File Format 337 Deriving and Implementing Your Image File Format Class 337 Opening an Existing File 338 Creating a New Image File 340 Closing a File 342 Parsing the File Name 344 Reading and Writing Formatted Data 345 Functions that Manipulate the Image Index 348 Adding Images to Image Files 349 x Contents Deriving an Image File Format from iflFormat 350 Deriving Subclasses 350 Virtual Function Descriptions 351 Sample Code for Virtual Function Definitions 353 Registering an Image File Format 354 Using the File Format Database 354 F. Auxiliary Classes, Functions, and Definitions 357 Auxiliary Classes 358 iflConfig 359 Using iflLut 360 Useful Functions 362 Computing the Size of Data Types 363 Minimum and Maximum Comparisons 364 Converting to Color-index Mode 364 Convenient Structures 365 Coordinate Data Structures 365 Error Codes 366 ilStatus Error Codes 366 iflStatus Error Codes 368 Enumerated Types and Constants 369 Describing Image Attributes 370 G. Using the Electronic Light Table 375 Understanding How ELT Works 375 DeWarping the Image 377 RotZooming the Image 377 Convolving the Image 377 Collecting Histogram Data 378 Dynamically Adjusting the Image 379 DeWarping the Image Data 379 Enabling and Disabling Operators 380 Setting Operator