Dll

DLL 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 USA Phone: 404/248-9000 Fax: 404/248-9400 User Support: 404/248-9777

Warning All information in this document, as well as the software to which it pertains, is proprietary material of ERDAS, Inc., and is subject to an ERDAS license and non-disclosure agreement. Neither the software nor the documentation may be reproduced in any manner without the prior written permission of ERDAS, Inc. Specifications are subject to change without notice.

Trademarks ERDAS is a trade name of ERDAS, Inc. ERDAS and ERDAS IMAGINE are registered trademarks of ERDAS, Inc. Model Maker, CellArray, ERDAS Field Guide, and ERDAS Tour Guides are trademarks of ERDAS, Inc. Other brands and product names are trademarks of their respective owners.

DLL On-Line Manual DLL Technology in IMAGINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 DLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 InstanceTitleListGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 InstanceDescriptionGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 InstanceTemplateListGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 InstanceExtListGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 InstanceIsCreatableFlagsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 InstanceFilterFlagsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 InstanceIsDirFlagsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 InstanceShortNameListGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 InstanceMagicListGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 FileTitleIdentifyAndOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 FileTitleIdentify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 FileDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 FileOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 FileClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 FileFlush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 FileModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 FileCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 FileRename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 FileDataModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 FileDataRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 FileDataWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 FileDataDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

RasterFormats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 InstanceCompressionTypesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 InstancePixelTypesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 InstanceLayerTypesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 InstanceRasterDataOrderTypesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 InstanceMapProjectionIsSupported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 FileLayerNamesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 FileLayerNamesSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

iii

DLL On-Line Manual FileRasterDataOrderGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 FileRasterDataOrderSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 FileCovarianceRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 FileCovarianceWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 FileDependentGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 FileDependentSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 FileDependentLayerNameGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 FileDependentLayerNameSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 FileRasterFormatsNonStandardDataNamesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 LayerCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 LayerDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 LayerOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 LayerClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 LayerLayerTypeRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 LayerLayerTypeWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 LayerRasterRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 LayerRasterWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 LayerRasterModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 LayerRasterRectangleReadInitiate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 LayerRasterRectangleReadCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 LayerRasterReadInitiate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 LayerRasterReadCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 LayerRasterNullValueRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 LayerRasterNullValueWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 LayerRRDLayerNamesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 LayerRRDLayerNamesSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 LayerScalarStatisticsRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 LayerScalarStatisticsWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 LayerMapInfoRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 LayerMapInfoWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 LayerMapToPixelTransformRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 LayerMapToPixelTransformWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 LayerMapProjectionRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 LayerMapProjectionWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 LayerHistogramRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 LayerHistogramModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

iv

DLL On-Line Manual LayerHistogramWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 LayerHistogramDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 LayerContrastRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 LayerContrastModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 LayerContrastWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 LayerContrastDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 LayerClassNamesRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 LayerClassNamesModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 LayerClassNamesWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 LayerClassNamesDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 LayerColorRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 LayerColorModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 LayerColorWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 LayerColorDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 LayerOpacityRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 LayerOpacityModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 LayerOpacityWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 LayerOpacityDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 gridInstanceTitleListGet . . . . . . . gridInstanceTemplateListGet . . . . . gridInstanceExtListGet . . . . . . . gridInstanceFilterFlagsGet . . . . . . gridInstanceIsDirFlagsGet . . . . . . gridInstanceIsCreatableFlagsGet . . . gridInstanceShortNameListGet . . . . gridInstanceCompressionTypesGet . . gridInstanceLayerTypesGet . . . . . gridInstancePixelTypesGet . . . . . . gridInstanceColumnTypesGet . . . . gridInstanceMapProjectionIsSupported gridFileTitleIdentify . . . . . . . . . gridFileOpen . . . . . . . . . . . . gridFileTitleIdentifyAndOpen . . . . gridFileClose . . . . . . . . . . . . gridFileLayerNamesGet . . . . . . . gridFileCopy . . . . . . . . . . . . gridFileDestroy . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171

v

DLL On-Line Manual gridFileModTimeGet . . . . gridFileRename . . . . . . gridFileDataRead . . . . . . gridFileDataModTimeGet . . gridLayerCreate . . . . . . gridLayerDestroy . . . . . . gridLayerOpen . . . . . . . gridLayerClose . . . . . . . gridLayerLayerTypeRead . . gridLayerRasterRead . . . . gridLayerRasterWrite . . . . gridLayerScalarStatisticsRead gridLayerMapInfoRead . . . gridLayerMapInfoWrite . . . gridLayerMapProjectionRead gridLayerMapProjectionWrite gridLayerRasterModTimeGet gridTableClose . . . . . . . gridTableColumnNamesGet . gridTableOpen . . . . . . . gridColumnModTimeGet . . gridColumnClose . . . . . . gridColumnDataRead . . . . gridColumnDataWrite . . . . gridColumnOpen . . . . . . gridColumnCreate . . . . . gridColumnDestroy . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

tiff . . . . . . . . . . . . . . . . . . . . . . . tiffInstanceTitleListGet . . . . . . tiffInstanceTemplateListGet . . . . tiffInstanceExtListGet . . . . . . . tiffInstanceShortNameListGet . . . tiffInstanceCompressionTypesGet . . tiffInstanceLayerTypesGet . . . . . tiffInstancePixelTypesGet . . . . . tiffInstanceIsCreatableFlagsGet . . . tiffInstanceMapProjectionIsSupported tiffFileTitleIdentifyAndOpen . . . . tiffFileClose . . . . . . . . . . . tiffFileLayerNamesGet . . . . . . tiffFileCopy . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

199 209 210 211 212 213 214 215 216 217 218 219 220 221

vi

DLL On-Line Manual tiffFileDestroy . . . . . . . . . . tiffFileFlush . . . . . . . . . . . tiffFileRename . . . . . . . . . . tiffLayerCreate . . . . . . . . . . tiffLayerDestroy . . . . . . . . . tiffLayerOpen . . . . . . . . . . tiffLayerClose . . . . . . . . . . tiffLayerLayerTypeRead . . . . . . tiffLayerRasterRead . . . . . . . tiffLayerRasterWrite . . . . . . . tiffLayerScalarStatisticsRead . . . . tiffLayerScalarStatisticsWrite . . . tiffLayerMapInfoRead . . . . . . tiffLayerMapInfoWrite . . . . . . tiffLayerMapToPixelTransformRead tiffLayerMapProjectionRead . . . . tiffLayerMapProjectionWrite . . . . tiffLayerColorModTimeGet . . . . tiffLayerColorRead . . . . . . . . tiffLayerColorWrite . . . . . . . . tiffLayerColorDestroy . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . .

222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242

uai . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uaiInstanceTitleListGet . . . . . . . . . . . . uaiInstanceDescriptionGet . . . . . . . . . . . uaiInstanceTemplateListGet . . . . . . . . . . uaiInstanceExtListGet . . . . . . . . . . . . . uaiInstanceShortNameListGet . . . . . . . . . uaiFileTitleIdentifyAndOpen . . . . . . . . . . uaiFileClose . . . . . . . . . . . . . . . . . uaiFileModTimeGet . . . . . . . . . . . . . . uaiFileDataModTimeGet . . . . . . . . . . . . uaiFileDataRead . . . . . . . . . . . . . . . uaiInstancePixelTypesGet . . . . . . . . . . . uaiInstanceLayerTypesGet . . . . . . . . . . . uaiFileLayerNamesGet . . . . . . . . . . . . uaiFileCovarianceRead . . . . . . . . . . . . uaiFileRasterFormatsNonStandardDataNamesGet . uaiLayerOpen . . . . . . . . . . . . . . . . uaiLayerClose . . . . . . . . . . . . . . . . uaiLayerLayerTypeRead . . . . . . . . . . . . uaiLayerRasterRead . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

243 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264

vii

DLL On-Line Manual uaiLayerRasterModTimeGet . . . . uaiLayerRasterNullValueRead . . . uaiLayerRRDLayerNamesGet . . . uaiLayerScalarStatisticsRead . . . . uaiLayerMapToPixelTransformRead uaiLayerMapInfoRead . . . . . . uaiLayerMapProjectionRead . . . . uaiInstanceColumnTypesGet . . . . uaiTableOpen . . . . . . . . . . uaiTableClose . . . . . . . . . . uaiTableColumnNamesGet . . . . . uaiColumnOpen . . . . . . . . . uaiColumnClose . . . . . . . . . uaiColumnModTimeGet . . . . . . uaiColumnDataRead . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

265 266 267 268 269 270 271 272 273 274 275 276 277 278 279

DescriptorTables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 InstanceColumnTypesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 TableOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 TableCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 TableDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 TableClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 TableColumnNamesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 TableColumnNamesSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 TableRowCountGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 TableRowCountSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 ColumnOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 ColumnCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 ColumnDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 ColumnClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 ColumnModTimeGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 ColumnDataRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 ColumnDataWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

GeometricModels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 XFormConvertFromMIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 XFormConvertToMIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

viii

DLL On-Line Manual XFormSscanf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 XFormSprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 XFormDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 XFormIsUsable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 XFormIsInverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 XFormInvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 XFormCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 XFormIsSame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 XFormTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 XFormTransformWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 XFormAffinePrepend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 XFormAffineAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 XFormAffineExtract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 affine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 polynomial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

ResampleMethods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 InstanceGeometricModelsInstanceListsGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 InstanceKernelSizeListGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 InstanceSrcDataTypesGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 ResampleDataCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 ResampleDataDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 ResampleBlockCheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 ResampleBlockInterpolate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

GeomodelInterfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 IsFileAppropriate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 ModelSupportsAutoCompute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 ModelSupportsForwardPredict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 ModelSupportsReversePredict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 ModelIsInvertable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 ModelSupportsGCPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 ModelNeedsElevation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 ModelNeedsReferenceProjection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 ModelIsFileBased . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

ix

DLL On-Line Manual ModelCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 ModelDestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 ModelConvertToMIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 ModelConvertFromMIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 ModelPropertiesDisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 ModelPropertiesRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 ModelReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 ModelElevationUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 ModelSolve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 ModelSolutionDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 ModelErrorDisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 ModelErrorRemove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 ModelXFormGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 XFormIsEditable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 XFormEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

ApplicationFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Eeml_AppFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

x

DLL Class DLL Technology in IMAGINE Description Summary In architecting systems that deliver customization options to end users, the creation of application programs which can be extended without recompiling or relinking becomes a highly desired goal. The shared library technology which is present under UNIX and Windows operating systems is traditionally used to develop applications which access code from shared libraries, which libraries are loaded by the system loader at the time the application is loaded, using instructions created in the application at the time it is linked. In the traditional approach, therefore, allowing the application to use different or additional libraries requires that the application be re-linked. This same shared library technology, however, can also be used to develop applications which can access code from shareable objects which are loaded at run-time, well after the application has been loaded by the system loader. At ERDAS, we distinguish shared objects/libraries which are loaded by an application at run time from objects/libraries which are loaded by the system loader when an application is loaded by designating the former as Demand Loaded Libraries (DLLs) and referring to the latter as shared libraries. DLLs can now be used in IMAGINE to provide a previously unavailable degree of extensibility. For example, DLLs may be used to provide “plug-in” functionality for dealing with RasterFormats, ApplicationFunctions, GeometricModels, and more. DLL Description A DLL is a shared library. It consists of one or more functions and a table of entry points which gives the names and locations of the functions within the library. Unlike a shared library, a DLL need not be present at the time the program which uses it is created. A program locates and opens a DLL by name at runtime. When a DLL is opened it is attached to the program’s address space and a handle to the DLL is returned. This handle can be used to look up the address of global functions in the library by name. Once a function’s address has been found, the function may be invoked through this address just like any other function. As an example, let us consider a system which is to provide an external means of defining functions which operate on two doubles to return a double result. The following example assumes that a DLL called “multiply.dll” has been developed. Example #include <stdio.h>

1

#include <edll.h> typedef double (*DoubleOp) __((double, double)); double a = 6.01; double b = 3.14; double c; DoubleOp func; Edll_Handle opdll;

/* ** Open the dll. Make sure to keep the handle which is retuned. */ opdll = edll_Open(“multiply.dll”); /* ** Now locate the function which we wish to use. For each ** Class of DLL the names of the functions will be the same ** We will assume in this case that the name of the function ** is DoubleOp. */ func = (DoubleOp)edll_Find(opdll, “DoubleOp”); /* ** Now refernce the function through the pointer. This function ** call is just as fast as any other function call. */ c = (*func)(a, b); /* ** When done close the DLL. Opening and closing the DLL should not ** be done at the level of the function call. In general a DLL ** would be opened and all functions located and recorded at some ** initialize point. The function pointers would then be used ** repeatedly, keeping the DLL open. Then when it is no longer ** needed, the DLL would be closed. */ edll_Close(opdll);

Conventions The previous example shows the mechanics of interacting with a DLL. So that DLLs may be used effectively in IMAGINE, we have established conventions which guide the ways in which DLLs are used and created. These conventions deal with the names and locations of DLLs as well as the organization of the contents of DLLs.

2

DLL Classes and Instances A separate set of Interface Function Definitions (IFDs) are developed for each Class of problem addressed by the use of DLLs. For example, each of the DLLs written to access data in raster files provides a subset of the same set of functions, even though each DLL deals with a different data format. The definition of the functions to be provided by a particular DLL are a part of the definition of the DLL Class. Each of the DLLs developed is an instance of a DLL Class. For each DLL class the following are defined: There is a directory in each of the library directories which is used to hold the DLL Instances for this class. For example, the directory $IMAGINE_HOME/usr/lib/<arch>/ FileFilters holds all of the file filters. Placing all of the DLLs for a given class in one directory makes searching for them faster. There is an environment variable reserved for each DLL class that holds the value of the search path to be used when looking for DLLs in that class. The name of the search path variable is based on the name of the DLL class. DLL classes are named using mixed case with upper case letters beginning words. Search path environment variable names are all upper case with underscores (“_”) between words. They all begin with “ERDAS_” and end with “_PATH”. For example: ERDAS_FILE_FILTERS_PATH=”./FileFilters:$IMAGINE_HOME/usr/lib// FileFilters”

Each DLL Instance contains one or more global functions with names and calling semantics that have been pre-defined by the DLL Class definition, i.e., implementations of IFDs. These global functions are searched for when the DLL is opened. The names of all global functions implementing IFDs in a particular DLL instance can either be the same as the IFD or can consist of the DLL name prepended to the IFD name. The latter option is provided for cases where it might be desirable to statically link one or more DLL instances into an executable. Allowing the global functions to have the DLL name prepended to them eliminates name conflicts during the static link. For example, the DLL Instance of the RasterFormats DLL Class that handles .img files (img.dll) implements the InstanceTitleListGet IFD by defining a global function named imgInstanceTitleListGet. Class Configuration Each class owner is responsible for maintaining a list of titles and associating those titles with the specific instance by which they are served. A convenient way to do this is to identify all instances of a class at runtime using the search path. Each instance could then be loaded and queried in turn. This provides the most dynamic maintenance method and allows new DLLs to be installed and recognized easily. A more efficient method is available. Many platforms incur a gread deal of overhead when

3

scanning the search path, particularly in cases involving networked file systems. There is also the unnecessary overhead of loading DLLs which may not be used during the current session. A more efficient method would provide a persistant means of recording the location of DLL instances, along with any information which might be used by the class owner for identifying which DLL instance will service a specific object. The IMAGINE Configuration Database provides just such a mechanism for storing information about DLL instances. DLL classes which use the configuration database need some means of updating the information outside of the IMAGINE user session. This is provided by a class specific configuration program which loads each instance DLL and retrieves any information which can be considered static (e.g. the TitleList). The configuration program, by convention, is named “configure_”, where is the prefix prepended to the development module directories for the instance modules of the DLL Class (such as ‘rf’ for the RasterFormats DLL Class). The information is stored in the base level of the database, which represents the architecture configuration. This level of the database cannot be edited by the user, so it will be relatively safe. The setup script for each platform will call all configuration programs found during system setup. Each DLL class owner will have its own database class in the configuration database. Within the database class, unique records will typically be identified by a title. Any other useful information, including the instance location, can be stored as a field in the record. With the static configuration information for a DLL class stored in the configuration database, it will be loaded automatically at application startup. The class owner should have enough information about all of the instances present to match an object with a title, and therefore a DLL instance, simply by querying the configuration database. The class can then load only those DLLs which are actually needed to handle the data being manipulated by the user. There is one pitfall to watch out for. Even though the base level of the configuration database can be considered safe from user manipulation, the class developer cannot be assured that the preconfigured information will be present. Therefore the class owner should be able to perform the dynamic configuration if it cannot find any preconfigured data in the database.

4

DLL Class DLLs Description The DLLs DLL Class is a virtual DLL Class (there are no instances of this DLL Class) from which all DLL Classes inherit. It defines interface functions that all DLL Classes may have in common. Refer to the DLL Technology in IMAGINE document for an explanation of what a DLL is and how it is used in the software. Instances in Current Version This is a virtual DLL Class from which all DLL Instances inherit. Therefore, any DLL instance present in IMAGINE implements the required interface functions from this DLL Class. Interface Function Definitions The interface functions defined for this DLL Class generally allow generic information about a DLL Instance to be obtained. Because of this, all of the names of these interface functions begin with the word “Instance”. The most important of these interface functions is the InstanceTitleListGet function which gives a name to each of the objects or methods supported by the DLL Instance.

5

Interface Function InstanceTitleListGet Syntax long InstanceTitleListGet( unsigned long *count, char ***titleList )

/* Output */ /* Output */

Arguments

count Returns a count of the titles supported by this instance.

titleList Returns a character string array holding the titles supported by this instance. Description The InstanceTitleListGet function is used to query a DLL for titles of objects or methods that are serviced by that DLL. The results of this function are intended to be used ultimately by user interface software so that appropriate title lists can be constructed and presented to the user based solely on what sort of input a particular interface is looking for and what DLLs are available. This function should set *titleList to a character string list of all titles (objects or methods) supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. The count of the strings in the list should be placed in *count. The function can expect count and titleList to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function must exist in the DLL. If the function does not exist or returns a NULL char ** pointer in *titleList, or returns a zero value in *count, or has a return value less than zero, the DLL will be ignored. Example The RasterFormats DLL to support ERDAS IMAGINE files defines an

6

InstanceTitleListGet function that returns a six element string list containing the strings “IMAGINE Image”, “PANEL”, “RRD”, “FFT”, “IMAGE CHIP”, and “AUX”.

7

Interface Function InstanceDescriptionGet Syntax long InstanceDescriptionGet( char **description; )

/* Output */

Arguments

description Returns a character string description of the DLL Instance. Description The InstanceDescriptionGet function is used to obtain a character string description of a particular DLL Instance. This function is intended to be used by a DLL Instance maintenance tool so that the particular version and update level of a DLL can be queried from the DLL and presented to the user for informational purposes. This function should set *description to a character string containing an indication of the purpose of the DLL Instance and its version and update level. The string should be dynamically allocated so as to be freeable by the caller. The function can expect description to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function is optional. If it is not present, minimal information can be given to the user concerning this DLL Instance. Example The RasterFormats DLL to support ERDAS IMAGINE files defines an InstanceDescriptionGet function that returns a character string that documents the last revision level and date of last revision of the source file containing the implementation of the DLL Instance. A brief description of the file format supported by the DLL Instance is also provided.

8

DLL Class Files Description The Files DLL Class is a virtual class derived from the DLLs DLL Class that defines a common interface to file based DLL Classes. The use of a DLL that implements an interface to a file system object is naturally initiated by the user through the user interface via file selection. Because the DLLs that implement an interface to a file system object have this common ground, there are several IFDs common to all DLLs of this type. Identification of Files File system object based DLL support is provided primarily to allow persistent file system objects to become the source and destination of in-memory operations, regardless of the data format of the file system object. Because of this, the file system object is a natural means of communicating to the system which DLL should be used to perform reading and writing of data. The key upon which this communication is based is a . The is a character string described in the efnp package documentation (all non-terminal grammar symbols denoted by enclosure in <> are defined in the efnp package unless otherwise noted). A may be as simple as a single . For their part, DLL writers need only be concerned with externalized ’s and root ’s. DLL Class IFDs should be defined such that the only efnp related objects that might be passed to a DLL instance via the IFD parameters are externalized ’s and root ’s. Using a as a key to object based DLL support allows objects within the file to be identified and it also allows identification of the DLL Instance intended to be utilized to be communicated clearly with the identification of the file system object to be accessed. This becomes important when the file format supported by a DLL Instance does not normally use an extension and the file does not yet exist. The user will communicate to the system through its interface that the file to be created is of a particular format and should have a particular name. The system’s interface is fully aware of what the user desires, but all of this information cannot be passed to another application component simply by specifying an output file name. Thus, the becomes the conveyer of this information. The component may be passed an output file in the form of a that has a pattern of () which will convey all of the necessary information. Externalized ’s are only required to conform to any restrictions imposed by the underlying file system. Specific DLL Classes may impose additional restrictions on the allowable characters used in these names, however.

9

Other conventions Some file system object interfaces provide access to objects that cannot be read and written atomically. These objects usually are composed of sub-objects. These types of objects typically have ‘create’, ‘destroy’, ‘open’ and ‘close’ IFDs. Normally, the sub-objects of the object will only be accessible after an identifier for the object has been obtained via either the ‘create’ or ‘open’ call. The ‘close’ call is used to indicate to the DLL Instance that the interface is finished accessing sub-objects of the object. The ‘destroy’ call is used to remove the object and all of its sub-objects. There may also be ‘get’ and ‘set’ IFDs that belong to the parent object that query and change the identifiers for objects of this type if there is more than one contained in the parent object. Objects that can be read and written atomically will dispense with the ‘close’ IFD. They will usually be supported by a ‘read’ IFD that implements an ‘open’ followed by a ‘close’. In addition, they will be supported by a ‘write’ IFD that implements a ‘destroy’ followed by a ‘create’ followed by a ‘close’. They may also be supported by a ‘destroy’ IFD that allows the object to be destroyed without being replaced. Instances in Current Version Among the DLL Classes defined in the current version of IMAGINE, RasterFormats is the only DLL Class that inherits from the Files DLL Class. Interface Function Definitions In addition to the interface functions inherited from the DLLs DLL Class, the Files DLL Class defines a number of interface functions for working with file based objects. These interface functions fall into two groups: Instance interface functions and File interface functions. Instance Interface Functions DLL Instances in classes inheriting from the Files DLL Class usually will have the Instance interface functions inherited from this class utilized in a user interface context, but these interface functions may be used elsewhere in the system. File Interface Functions The File Interface functions are used to obtain a file handle and to perform operations on the file in the file system. The fileName parameter used by many of these IFDs is defined as an externalized (see efnp).

10

Interface Function InstanceTemplateListGet Syntax long InstanceTemplateListGet( char ***tempList, char **tempListPseudoFlags )

/* Output */ /* Output */

Arguments

tempList Returns a list of file name templates, one per title supported by the DLL Instance. tempListPseudoFlags Returns a list of boolean flags indicating whether the corresponding template is really a pseudo-template. Description The InstanceTemplateListGet function is used to query a DLL for pattern matching string(s) that a user can use to filter a list of files of a type supported by this DLL. A pattern matching string is a NULL terminated ASCII character string, interpreted under the same rules defined by the estr_WildCompare function, usually of the form “*.<Ext>” where <Ext> represents an extension or pseudoextension. (A pseudoextension is used if the files supported by this DLL do not normally have an extension. The user can use the pseudoextension to allow the interface to determine which DLL the user actually wants to use to filter the files). Whether or not the template, (*tempList)[i], consists of a real extension or pseudoextension should be indicated by (*tempListPseudoFlags)[i]. This function should place a character string list in *tempList which contains pointers to all pattern matching strings for files supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. The count of the strings in the list should be exactly the same as the *count returned by the InstanceTitleListGet function. The list of templates should also be in the same order as the list of titles returned by the InstanceTitleListGet function. The function should place an array of characters in *tempListPseudoFlags that indicates whether or not the corresponding pattern matching string is a pseudoextension (non-zero) or a real extension (0). Optionally, *tempListPseudoFlags

11

may be set to NULL, in which case all of the pattern matching strings will be interpreted as real extensions. The function can expect tempList and tempListPseudoFlags to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function must exist in the DLL. If the function does not exist or returns a NULL char ** pointer in *tempList or has a return value less than zero the DLL will be ignored. Example The RasterFormats DLL to support ERDAS IMAGINE .img files defines an InstanceTemplateListGet function that returns a six element string list containing the strings “*.img”, “*.panel_*”, “*.rrd”, “*.fft”, “*.chp”, and “*.aux”.

12

Interface Function InstanceExtListGet Syntax long InstanceExtListGet( char ***extList )

/* Output */

Arguments

extList Returns a list of extensions, one per title supported by the DLL Instance. Description The InstanceExtListGet function is used to query a DLL for string(s) that should be used as extensions of file names for files of the types supported by the DLL instance. User interface components which prompt the user for names of files may append these strings directly to the name given by the user. An <Ext> string is a NULL terminated ASCII character string which usually begins with a period (“.”). If a period (“.”) is desired, it should be included in the string. The developer should pay special attention to ensure that the templates from InstanceTemplateListGet and the extensions from InstanceExtListGet are compatible. This function should place a character string list in *extList which contains pointers to all <Ext> strings for files supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. The count of the strings in the list should be exactly the same as the *count returned by the InstanceTitleListGet function. The list of extensions should also be in the same order as the list of titles returned by the InstanceTitleListGet function. The function can expect extList to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function must exist in the DLL. If the function does not exist or returns a NULL char ** pointer in *extList or has a return value less than zero the DLL will be ignored.

13

Example The RasterFormats DLL to support ERDAS IMAGINE .img files defines an InstanceExtListGet function that returns a six element string list containing the strings “.img”, “.panel”, “.rrd”, “.fft”, “.chp”, and “.aux”.

14

Interface Function InstanceIsCreatableFlagsGet Syntax long InstanceIsCreatableFlagsGet( char **flagsList )

/* Output */

Arguments

flagsList Returns a list of flags, one per title supported by the DLL Instance, indicating the ability of the DLL to create files of that title. Description The InstanceIsCreatableFlagsGet function is used to query a DLL for information about the files it supports. The flags indicate whether the titles supported by the DLL represent file formats which are directly creatable through the FileTitleIdentifyAndOpen or FileOpen function of the DLL. Titles corresponding to formats that are directly creatable through the DLL by invoking the FileTitleIdentifyAndOpen or FileOpen function using a fileMode that indicates creation (e.g., “wb+”) should have a corresponding flag value of 1. Otherwise, the corresponding flag value should be zero. This function should place a character array in *flagsList which contains char values of 0 or 1. The array should be dynamically allocated so as to be freeable by the caller. The count of the chars in the array should be exactly the same as the *count returned by the InstanceTitleListGet function. The list of flags should also be in the same order as the list of titles returned by the InstanceTitleListGet function. The function can expect flagsList to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function is optional. If the function does not exist or has a return value less than zero, a file of a format represented by any title supported by the DLL Instance will be assumed to not be creatable through the DLL.

15

Example The RasterFormats DLL to support ERDAS IMAGINE .img files defines an InstanceIsCreatableFlagsGet function that returns a six element char array containing the values 1, 1, 1, 1, 1, 1 indicating that files in the format of any title supported by this DLL are creatable through the DLL.

16

Interface Function InstanceFilterFlagsGet Syntax long InstanceFilterFlagsGet( char **flagsList )

/* Output */

Arguments

flagsList Returns a list of flags, one per title supported by the DLL Instance, indicating the suitability of a particular title in a user interface context. Description The InstanceFilterFlagsGet function is used to query a DLL for information about the files it supports. The flags indicate whether the titles supported by the DLL represent files which should be made available to the user in the user interface, or files which are used internally and are to be hidden from the user. User interface components which prompt the user for names for new files will ignore the titles with flags set to 0. If the title should be listed in the user interface, the flag should be set to 1. This function should place a character array in *flagsList which contains char values of 0 or 1. The array should be dynamically allocated so as to be freeable by the caller. The count of the chars in the array should be exactly the same as the *count returned by the InstanceTitleListGet function. The list of flags should also be in the same order as the list of titles returned by the InstanceTitleListGet function. The function can expect flagsList to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function is optional. If the function does not exist or has a return value less than zero, all titles supported by the DLL Instance will be assumed to be suitable for direct use by the user.

17

Example The RasterFormats DLL to support ERDAS IMAGINE .img files defines an InstanceFilterFlagsGet function that returns a six element char array containing the values 1, 1, 0, 0, 0, 0 indicating that only .img and .panel files are suitable for direct consumption by the user.

18

Interface Function InstanceIsDirFlagsGet Syntax long InstanceIsDirFlagsGet( char **flagsList )

/* Output */

Arguments

flagsList Returns a list of flags, one per title supported by the DLL Instance, indicating whether the title is file based or directory based. Description The InstanceIsDirFlagsGet function is used to query a DLL for information about the files it supports. The flags indicate whether the titles supported by the DLL represent file system objects which are files or directories. Some data formats are actually stored in multiple files in a subdirectory on the file system. A value of 1 in (*flagsList)[i] indicates that the format for the associated title is actually a directory. This function should place a character array in *flagsList which contains char values of 0 or 1. The array should be dynamically allocated so as to be freeable by the caller. The count of the values in the array should be exactly the same as the *count returned by the InstanceTitleListGet function. The list of flags should also be in the same order as the list of titles returned by the InstanceTitleListGet function. The function can expect flagsList to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function is optional. If the function does not exist or has a return value less than zero, all titles supported by the DLL Instance will be assumed to be file system objects which are files. Example The RasterFormats DLL to support the raster data format developed by ESRI defines an

19

InstanceIsDirFlagsGet function that returns a two element char array containing the values 1, 0 indicating that GRID coverages are stored in directories and GRID Stacks are stored in files.

20

Interface Function InstanceShortNameListGet Syntax long InstanceShortNameListGet( char ***namesList )

/* Output */

Arguments

namesList Returns a list of names, one per title supported by the DLL Instance, to be used in an icon registry. Description The InstanceShortNameListGet function is used to query a DLL for <ShortName> string(s) for the titles it supports. The return values are strings which can be used with icon registries (such as with WindowsNT or CDE) to associate files of a certain type with an appropriate icon. A <ShortName> string is a NULL terminated ASCII character string which usually contains no whitespace characters. The developer should pay special attention to ensure that the <ShortName>s chosen do not conflict with others already in the system. The strings are meant to uniquely associate a file format with a representative icon image. This function should place a character string list in *namesList which contains pointers to all <ShortName> strings for titles supported by this DLL. The array should be dynamically allocated so as to be freeable by the caller. The count of strings in the list should be exactly the same as the *count returned by the InstanceTitleListGet function. Each string in the list should also be dynamically allocated so as to be freeable by the caller. The list of strings should also be in the same order as the list of titles returned by the InstanceTitleListGet function. The function can expect namesList to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function must exist in the DLL. If the function does not exist or has a return value less than zero the DLL will be ignored.

21

Example The RasterFormats DLL to support ERDAS IMAGINE .img files defines an InstanceShortNameListGet function that returns a six element string list containing the strings “img”, “panel”, “rrd”, “fft”, “chp”, and “aux”.

22

Interface Function InstanceMagicListGet Syntax long InstanceMagicListGet( char ***magicList )

/* Output */

Arguments

magicList Returns a list of <Magic> strings, one per title supported by the DLL Instance. Description The InstanceMagicListGet function is used to query a DLL for <Magic> string(s) that may be used to compile an in-memory magic file of the type used by the UNIX ‘file’ command. When presented with a file, the class owner of a DLL Class that inherits from the Files DLL Class must determine which DLL Instance is to be used to handle that file. If the extension of the file matches the extension of one of the titles supported by a DLL Instance in its class, the class owner can make an excellent first guess about which DLL Instance supports that file. The class owner can then use the FileTitleIdentify or FileTitleIdentifyAndOpen function to confirm this guess. If the initial guess is incorrect or if the file does not have an extension that matches the extensions of any of the titles supported by DLL Instances in its class, the class owner has no choice but to invoke the FileTitleIdentify or FileTitleIdentifyAndOpen function of each DLL Instance until the DLL Instance that supports the specified file is found. By providing this function, a DLL Instance will give the class owner the information needed to ‘rule-out’ the DLL Instance as possibly supporting the file at hand. This may speed file identification by potentially avoiding loading the DLL Instance as well as by avoiding invoking the FileTitleIdentify or FileTitleIdentifyAndOpen function of the DLL Instance (probably avoiding another expensive opening of the file). A <Magic> string is a NULL terminated ASCII character string in the format supported by the UNIX ‘file’ command (use ‘man file’ for further information). The description of this format can be found under the man page listing for ‘magic’. The string may contain embedded new-line characters to support simulation of multi-line entries in the magic file. In addtion to <Magic> strings of the form described in the man page listing for ‘magic’, the following syntax is also recognized:

23

ASCII+0x00: ASCII-0x00: ASCII

These strings should be used for format titles that represent formats that consist of all ASCII characters, but otherwise have no magic strings or numbers that can be described through the magic syntax. The first and second forms specify that the format must contain only the subset of ASCII characters specified in . If the first form is used, ASCII NUL is allowed by this format; if the second form is used, ASCII NUL is not allowed by this format. The third form is a short-hand synonym for the second form with a that specifies ASCII code values (octal) 011 through 015 inclusive and 040 through 0176 inclusive (i.e., printable characters plus white space as defined by the C locale). Describing the format with one of the special ‘ASCII’ magic strings allows the class owner to rule this format out if the file it is currently considering contains characters that are not part of the format’s ASCII character list. This function should place a character string list in *magicList which contains pointers to <Magic> strings for each title supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. The count of the strings in the list should be exactly the same as the *count returned by the InstanceTitleListGet function. The list of <Magic> strings should also be in the same order as the list of titles returned by the InstanceTitleListGet function. As many of the strings as possible should be non-NULL, otherwise the purpose of providing magic information may be made less effective (because use of the DLL cannot be ruled out). The function can expect magicList to be non-NULL. Return Value The function should return 0 on success and -1 on failure. Requirements This function is optional. If the function does not exist or has a return value less than zero, the class owner must invoke the FileTitleIdentify or FileTitleIdentifyAndOpen function to definitively rule out the use of this DLL for a specific file. It is futile for DLL Instances that support only directory based formats to provide this interface function because there is no way to identify directory based formats through magic syntax.

24

Example The RasterFormats DLL to support ERDAS IMAGINE .img files defines an InstanceMagicListGet function that returns a six element string list containing the same magic string for each of the six titles supported. This magic string allows a file to be identified as a potential HFA file. The content of the magic string is (with tabs and newlines indicated): “0\tstring\tEHFA_HEADER_TAG\tERDAS IMAGINE HFA File\n >64\tbyte\tx\t- version %d”

This allows the class owner to deduce that if the first bytes of the file are not the ASCII characters for “EHFA_HEADER_TAG”, then the file is definitely NOT of a format supported by the DLL. Note that this string contains an embedded new-line. The second line of the magic string is superflous for ruling out the file as one supported by the IMG DLL, but is retained simply as a further example of magic text of the sort used by the UNIX ‘file’ command.

25

Interface Function FileTitleIdentifyAndOpen Syntax void * FileTitleIdentifyAndOpen( char *fileName, long *fileType, char *fileMode )

/* Input */ /* In/Out */ /* Input */

Arguments

fileName Specifies a to be identified and opened. fileType Specifies a type of file to create or returns the type of file opened. fileMode Specifies the access mode to be used when opening the file. Description The FileTitleIdentifyAndOpen function is intended to support both file identification functionality and file open functionality. Both functionalities are embodied in a single IFD for efficiency reasons (for existing files, the file will need to be opened to perform proper identification). The identification functionality determines whether or not fileName appears to be of the type supported by this DLL. Whereas the template list returned by the InstanceTemplateListGet function would be used to filter a list of files to restrict them to the files handled by this DLL, or to confirm that this DLL should be used to create a file of this type, this functionality would be used when the file actually exists to verify the file format. This function can expect fileName and fileType to be non-NULL. If fileMode is NULL or fileMode does not indicate file creation (see below), the function can also assume that fileName exists. If fileMode is non-NULL, the FileTitleIdentifyAndOpen function should open the file identified by fileName with the access mode identified by fileMode, assuming an inspection of the contents of fileName indicates that it is of a type supported by the DLL Instance.

fileMode may be any one of the initial string of characters valid for the mode argument of 26

the ANSI fopen function. Practically speaking, however, the fileMode will most likely be one of the following: “rb”, “r+b”, “rb+”, “w+b” or “wb+” Each DLL Class that inherits from Files discusses the actual allowable fileMode’s for that Class. If fileMode is NULL or fileMode does not indicate file creation, the function should set *fileType to the index into the string list returned by the InstanceTitleListGet function of the file format title for fileName if fileName appears to be supported by this DLL. If there is no match, *fileType should be set to -1. If *fileType is less than zero or greater than *count - 1, where *count is the *count returned by the InstanceTitleListGet function, *fileType will be interpreted as a -1 (failure, i.e., not supported). For fileMode’s indicating that the file is to be created, the function should interpret *fileType as an indication of the file format to use when creating the file. The function can assume in these cases that *fileType will represent a valid index into the string list returned by the InstanceTitleListGet function. The DLL Instance should actually create the file in the file system before returning from the FileTitleIdentifyAndOpen call or the behavior of the system is undefined. If the creation is not performed prior to returning, resources, such as file handles, cannot be shared properly between multiple objects intended for the same file. Return Value If fileMode is non-NULL and the file open is successful, a pointer to DLL owned memory representing the open file should be returned. If the function is unable to open the file, a NULL pointer should be returned. *fileType should also be set to -1 in this case. Upon failure, the DLL may set errno. In general, the value in errno will simply be used to enhance the error reporting of the function calling the FileTitleIdentifyAndOpen function. The one exception to this is that if errno is equal to EACCES, the calling function may try to open the file again with a different access mode. Therefore, the DLL should ensure that errno is set to EACCES if the reason for the failure is due to file access permissions. The DLL should also ensure that errno is zero before return if the function call succeeded. Requirements Either this function must exist in the DLL or both the FileTitleIdentify and the FileOpen functions must exist. If this condition is not met, the DLL will be ignored. Providing this function will make DLL access more efficient than if the FileTitleIdentify/ FileOpen pair is provided.

27

Example If the “/data/large.img” were passed to the FileTitleIdentifyAndOpen function defined in the RasterFormats DLL that supports .img files, *fileType would be set to 0. If the “/data/mymap.panel_13” were passed, *fileType would be set to 2. If the “/data/large.dat” were passed, however, *fileType would be set to -1(assuming that this file is not in .img format). In the first two examples, the function also returns a pointer to DLL owned memory representing the open file if fileMode was not NULL.

28

Interface Function FileTitleIdentify Syntax long FileTitleIdentify( char *fileName )

/* Input */

Arguments

fileName Specifies a to be identified. Description The FileTitleIdentify function determines whether or not fileName appears to be of the type supported by this DLL. Whereas the template list returned by the InstanceTemplateListGet function would be used to filter a list of files to restrict them to the files handled by this DLL, or to confirm that this DLL should be used to create a file of this type, this function would be used when the file actually exists to verify the file format. This function can expect fileName to be non-NULL and to exist. Return Value The function should return the index into the string list returned by the InstanceTitleListGet function of the file format title for fileName if fileName appears to be supported by this DLL. If there is no match, -1 should be returned. If the returned value is less than zero or greater than *count - 1, where *count is the *count returned by the InstanceTitleListGet function, the return will be interpreted as a -1 (failure, i.e., not supported). Requirements Either both this function and the FileOpen function must exist in the DLL or the FileTitleIdentifyAndOpen function must exist in the DLL. If this condition is not met, the DLL will be ignored. Example If the “/data/large.img” were passed to the FileTitleIdentify function defined in the RasterFormats DLL that supports .img files, 0 would be returned. If the “/data/mymap.panel_13” were passed, 2 would be returned. If the “/data/large.dat” were passed, however, -1 would be returned (assuming that this file is not in .img format).

29

Interface Function FileDestroy Syntax long FileDestroy( char *fileName )

/* Input */

Arguments

fileName Specifies a indicating a file be destroyed. Description The FileDestroy function should remove the object identified by fileName. If the DLL supports directory objects, such as the ESRI GRID coverage DLL, the entire directory and its contents should be removed. Return Value This function should return 0 on success and -1 on failure. Any non-zero return value will be interpreted as failure. Requirements This function is optional. If this function is not provided, the system will attempt to remove the file system object by calling the system function appropriate for removing file system objects, such as the ‘unlink’ function call on UNIX systems.

30

Interface Function FileOpen Syntax void * FileOpen( char char )

*fileName, *fileMode

/* Input */ /* Input */

Arguments

fileName Specifies a to be opened. fileMode Specifies the access mode to be used when opening the file. Description The FileOpen function should open the file identified by fileName with the access mode identified by fileMode.

fileMode may be any one of the initial string of characters valid for the mode argument of the ANSI fopen function. Practically speaking, however, the fileMode will most likely be one of the following: “rb”, “r+b”, “rb+”, “w+b” or “wb+” Each DLL Class that inherits from Files discusses the actual allowable fileMode’s for that Class. If the FileOpen function call is successful, a pointer to DLL owned memory representing the open file should be returned. For fileMode’s indicating that the file is to be created, the DLL Instance should actually create the file in the file system before returning from the FileOpen call or the behavior of the system is undefined. If the creation is not performed prior to returning, resources, such as file handles, cannot be shared properly between multiple objects intended for the same file.

fileName and fileMode can be assumed to be non-NULL. Return Value If the FileOpen function call is unsuccessful, a NULL pointer should be returned. Upon failure, the DLL may set errno. In general, the value in errno will simply be used to

31

enhance the error reporting of the function calling the FileOpen function. The one exception to this is that if errno is equal to EACCES, the calling function may try to open the file again with a different access mode. Therefore, the DLL should ensure that errno is set to EACCES if the reason for the failure is due to file access permissions. Likewise, the DLL should ensure that errno is set to zero if the function call has been successfully completed. Requirements Either both this function and the FileTitleIdentify function must exist in the DLL or the FileTitleIdentifyAndOpen function must exist in the DLL. If this condition is not met, the DLL will be ignored.

32

Interface Function FileClose Syntax long FileClose( void )

*fileHandle

/* Input */

Arguments

fileHandle Specifies the file handle to be closed. Description The FileClose function should close the file identified by fileHandle. fileHandle can be assumed to be a value obtained from a previous call to either the FileOpen function or the FileTitleIdentifyAndOpen function. The function should free any memory associated with fileHandle. This function can expect fileHandle to be non-NULL. Return Value This function should return 0 on success and -1 on failure. Any non-zero return value will be interpreted as failure. Requirements This function must exist in the DLL. If the function does not exist the DLL will be ignored.

33

Interface Function FileFlush Syntax long FileFlush( void )

*fileHandle

/* Input */

Arguments

fileHandle Specifies the file handle to be flushed. Description The FileFlush function should flush the file identified by fileHandle. fileHandle can be assumed to be a value obtained from a previous call to either the FileOpen function or the FileTitleIdentifyAndOpen function. To ‘flush’ a file means to ensure that any data that has been written to the file has been written to the disk (and is not merely sitting in a memory buffer being accessed by the process). If the file is open without write permission, to ‘flush’ the file means to unremember all data that has previously been read (in case it has been read into a memory buffer that is being accessed by the process). This function can expect fileHandle to be non-NULL. Return Value This function should return 0 on success and -1 on failure. Any non-zero return value will be interpreted as failure. Requirements This function is optional, but recommended.

34

Interface Function FileModTimeGet Syntax long FileModTimeGet( char *fileName, time_t *modTime )

/* Input */ /* Output */

Arguments

fileName Specifies a to be queried. modTime Returns the last modification time of fileName. Description The FileModTimeGet function should retrieve the time of the last modification to the file indicated by fileName and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the file does not exist, (time_t)-1 should be placed in *modTime. (time_t is an ANSI C defined data type obtainable by including .)

fileName and modTime can be expected to be non-NULL. Return Value A zero should be returned on success and a -1 on failure. Requirements This function is optional. If the DLL does not provide this function, the modification time will be retrieved by calling the POSIX stat function.

35

Interface Function FileCopy Syntax long FileCopy( char char void long )

*sourceName, *destName, *data, (*progress)( void *, double )

/* Input */ /* Input */ /* Input */ /* Input */

Arguments

sourceName Specifies a indicating the source of the copy. destName Specifies a indicating the destination of the copy. data Specifies opaque data to be passed to the progress function.

progress Specifies a function to be called periodically to indicate copy progress. Description The FileCopy function should copy the contents of sourceName to destName nondestructively (destName should not be overwritten if it exists). If progress is non-NULL, it is a function that should be called intermittently while copying the file. The data pointer should be passed as the first parameter to the function and the percent of the file (i.e., a number between 0.0 and 100.0) copied thus far should be passed as the second parameter. The progress function will return a non-zero value if the copy has been interrupted by the user, zero otherwise. If the copy is interrupted or an error occurs, destName and any files related to destName should be removed (assuming, of course, that the error is not that destName already exists).

sourceName and destName can be assumed to be non-NULL. This function is intended for file based objects that span multiple files or have file formats that may contain internal free space.

36

Return Value The function should return 0 for success, -1 for failure and 1 for user interrupt. Requirements This function is optional for file objects which exist as a single file. If the function does not exist, the operating system equivalent of a file copy will be performed on the file object.

37

Interface Function FileRename Syntax long FileRename( char *sourceName, char *destName )

/* Input */ /* Input */

Arguments

sourceName Specifies a indicating the source of the copy. destName Specifies a indicating the destination of the copy. Description The FileRename function should rename the file object at sourceName to destName nondestructively (destName should not be removed to allow the rename to succeed).

sourceName and destName can be assumed to be non-NULL. Return Value The function should return 0 for success and -1 for failure. Requirements This function is optional for file based objects which exist in a single file. If the function does not exist, the operating system equivalent of a file rename (e.g., ‘mv’ in the UNIX operating system) will be performed on the file object.

38

Interface Function FileDataModTimeGet Syntax long FileDataModTimeGet( void *fileHandle, char *dataName, time_t *lastModTime )

/* Input */ /* Input */ /* Output */

Arguments

fileHandle Specifies the file handle to be queried. dataName Specifies the name of a data object contained within fileHandle. lastModTime Returns the last modification time of dataName. Description The FileDataModTimeGet function allows the last modification time of the arbitrary data object named in dataName to be obtained from the open file handle, fileHandle. fileHandle can be assumed to be a value obtained from a previous call to either the FileOpen function or the FileTitleIdentifyAndOpen function. dataName is a that uniquely identifies the object. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the object does not exist in the file, (time_t)-1 should be placed in *modTime. (time_t is an ANSI C defined data type obtainable by including .)

fileHandle, dataName, and lastModTime can be expected to be non-NULL. Return Value The function should return 0 for success and -1 for failure. Requirements This function is optional.

39

Interface Function FileDataRead Syntax long FileDataRead( void char unsigned char unsigned long char char )

*fileHandle, *dataName, **MIFDataObject, *MIFDataSize, **MIFDataDictionary, **MIFDataType

/* Input */ /* Input */ /* Output */ /* Output */ /* Output */ /* Output */

Arguments

fileHandle Specifies the file handle from which to read. dataName Specifies the name of the object to read from fileHandle. MIFDataObject Returns a MIF version of the dataName object. MIFDataSize Returns the size of MIFDataObject. MIFDataDictionary Returns a data dictionary containing a data design describing MIFDataObject. MIFDataType Returns the design name in MIFDataDictionary representing MIFDataObject. Description The FileDataRead function allows the arbitrary data object named in dataName to be read from the open file handle, fileHandle. fileHandle can be assumed to be a value obtained from a previous call to either the FileOpen function or the FileTitleIdentifyAndOpen function. dataName is a that uniquely identifies the object. If the named object is found in the file, the return parameters should be set to describe the object. *MIFDataObject should be set to point to a memory buffer that contains a Machine

40

Independent Format (MIF) version of the object (see emif). This memory buffer should be dynamically allocated so as to be freeable by the caller. *MIFDataSize should be set to the number of bytes contained in *MIFDataObject. *MIFDataDictionary should be set to point to a character string that represents the ASCII encoding of the MIF data dictionary describing the *MIFDataObject. This character string should be NULL terminated and should be dynamically allocated so as to be freeable by the caller. *MIFDataType should be set to point to a character string that represents the name of the definition in *MIFDataDictionary that defines *MIFDataObject. This character string should be NULL terminated and should be dynamically allocated so as to be freeable by the caller. Return Value The function should return 0 for success and -1 for failure. If the named object is NOT found in the file, this should not be treated as an error. In this case, 0 should be returned but *MIFDataObject, *MIFDataDictionary, and *MIFDataType should all be set to NULL and *MIFDataSize should be set to zero. Requirements This function is optional. This function will be ignored if the FileDataModTimeGet function is not present.

41

Interface Function FileDataWrite Syntax long FileDataWrite( void char unsigned char unsigned long char char )

*fileHandle, *dataName, *MIFDataObject, MIFDataSize, *MIFDataDictionary, *MIFDataType

/* Input */ /* Input */ /* Input */ /* Input */ /* Input */ /* Input */

Arguments

fileHandle Specifies the file handle to which to write. dataName Specifies the name of the object to write to fileHandle. MIFDataObject Specifies a MIF version of the dataName object. MIFDataSize Specifies the size of MIFDataObject. MIFDataDictionary Specifies a data dictionary containing a data design describing MIFDataObject. MIFDataType Specifies the design name in MIFDataDictionary representing MIFDataObject. Description The FileDataWrite function allows the arbitrary data object named in dataName to be written to the open file handle, fileHandle. fileHandle can be assumed to be a value obtained from a previous call to either the FileOpen function or the FileTitleIdentifyAndOpen function that has been opened in a mode that allows modification. dataName is a that uniquely identifies the object. The object should be written so that an attempt to retrieve an object named dataName from the same file through the FileDataRead function will return identical parameters as those submitted during a call to this function.

MIFDataObject points to a memory buffer that contains a Machine Independent Format

42

(MIF) version of the object (see emif).

MIFDataSize indicates the number of bytes contained in MIFDataObject. MIFDataDictionary points to a character string that represents the ASCII encoding of the MIF data dictionary describing MIFDataObject. MIFDataType points to a character string that represents the name of the definition in MIFDataDictionary that defines MIFDataObject. Return Value The function should return 0 for success and -1 for failure. Requirements This function is optional. This function will be ignored if the FileDataRead function is not present.

43

Interface Function FileDataDestroy Syntax long FileDataDestroy( void *fileHandle, char *dataName )

/* Input */ /* Input */

Arguments

fileHandle Specifies the file handle in which to destroy data. dataName Specifies the name of the object to destroy in fileHandle. Description The FileDataDestroy function allows the arbitrary data object named in dataName to be removed from the open file handle, fileHandle. fileHandle can be assumed to be a value obtained from a previous call to either the FileOpen function or the FileTitleIdentifyAndOpen function that has been opened in a mode that allows modification. dataName is a that uniquely identifies the object. Return Value The function should return 0 for success and -1 for failure. If the data to be destroyed does not exist in the file, the function should not treat this as an error. Requirements This function is optional. This function will be ignored if the FileDataRead function is not present.

44

DLL Class RasterFormats Description The RasterFormats DLL Class provides a uniform interface for raster imagery access. Since it is designed to support arbitrary raster file formats, the class supports read and write operations not only on the raster data of an image, but also on the complete set of auxiliary information (e.g., georeferencing, geocoding, image statistics, contrast, color and other attribute information) associated with the raster data set. The RasterFormats Class owner package, eimg, defines a set of API functions that provide read and write access to raster data and its associated auxiliary information. True application-transparent support for arbitrary raster file formats can be achieved by an application if that application accesses raster data and its associated auxiliary information solely through the eimg API. The eimg package is responsible for loading raster and auxiliary data access functions from the appropriate DLL in this DLL Class. The appropriate DLL is identified through a query of the available DLL’s based on a key (i.e., the file name) that the DLL can use to determine whether or not it can support the image in question. All operations on images through the eimg interface may be supported for arbitrary file formats by constructing an appropriate DLL. The RasterFormats Class, then, is defined by IFDs that allow raster imagery and associated auxiliary information to be read and written to the file format supported by a particular DLL. The class is derived from the Files DLL Class and also inherits the DescriptorTables DLL Interface definition, although the implementation of this interface within a RasterFormats DLL instance is optional. The class definition does not prohibit multiple file formats from being handled by the same DLL. However, certain IFDs, such as the IFD for the function that queries the compression types supported by the DLL, do not take a file type, a file name or file handle as an argument. This means that the DLL must support all compression types for all file formats supported by that DLL in order for the DLL to behave properly in the IMAGINE environment. Identification of layers A set of raster data representing a single measurement or a single thematic description is termed a ‘layer’ in IMAGINE. Traditionally, layers have been identified with layer names so that the in-memory layer objects may be associated with a persistent file system object. These persistent file system objects are the source and destination of image layer data and its modifications. The eimg package defines a way to address a layer object by name and calls this construct a full layer name.

45

DLLs will not be required to know about the construction of a full layer name (as a ) unless they implement RRD access for a layer (see LayerRRDLayerNamesGet). They will need to know about externalized ’s and ’s, however, and will have to form appropriate names based on the definitions of these entities (see efnp). Instances in Current Version The following instances of RasterFormats DLLs are distributed with the current version of IMAGINE. DLL Instance

Description

e7x.dll

ERDAS LAN/GIS Image Access

fit.dll

SGI FIT Image Access

gif.dll

GIF Image Access

grid.dll

ESRI GRID Image Access

img.dll

IMAGINE Image (Native) Access

jfif.dll

JPEG Compressed Image Access

raw.dll

IMAGINE RAW Image Access, Generic Binary Export Image Access, ARC/INFO BIL Image Access, ER Mapper Image Access

tiff.dll

TIFF Version 6.0 Image Access

Interface Function Definitions The RasterFormats DLL Class derives from the Files DLL Class which derives from the DLLs DLL Class. As such, all required IFDs from these two DLL Classes are also required for the RasterFormats DLL Class. The RasterFormats DLL Class also inherits the DescriptorTables DLL interface. If a RasterFormats DLL instance chooses to implement this interface, all required IFDs from this interface are also required in the RasterFormats DLL instance. The complete set of RasterFormats IFDs fall into the following categories: DLL Instance IFDs The DLL Instance IFDs for the RasterFormats DLL Class are used by user interface functions to supply appropriate choices to users in a context where a file supported by a specific DLL Instance may be created or modified. They apply not

46

to a specific file, but to all files supported by the DLL Instance. File IFDs The File IFDs for the RasterFormats DLL Class all take a file handle as an argument. This file handle is obtained from the FileOpen function, which is one of several interface functions inherited from the Files DLL Class. Layer IFDs The Layer IFDs defined in the RasterFormats DLL Class definition all deal with access to individual raster layers and their associated auxiliary information. They all either take or return a layer handle as an argument. Table and Column IFDs The Table and Column IFDs are inherited from the DescriptorTables DLL Class. The dataSource argument that is passed into the TableOpen and TableCreate interface functions is the file handle returned by the FileOpen interface function, so the DLL instance supporting this interface should implement these interface functions accordingly, if it is desired to support this interface. “Easy” Descriptor Table Access Layer IFDs The “Easy” Descriptor Table Access Layer IFDs are function definitions which provide an alternative means for DLL Instances to provide access to descriptor information associated with an image layer. For many raster formats, the “fullblown” Table and Column IFDs are not necessary and would be more difficult to implement. There are several restrictions, however, on the use of these “Easy” Descriptor Table Access Layer IFDs. Refer to the eimg API for how these interface functions will be interpreted and used by the class owner. The table below summarizes the interface functions that a RasterFormats DLL instance may implement, with an indication of which functions are actually required in order for the DLL instance to be recognized as valid for the RasterFormats DLL class. The DLL writer should consult the documentation for the associated DLL Classes for a complete description of the required and optional interface functions From Class

IFD InstanceTitleListGet

DLLs

InstanceDescriptionGet

DLLs

InstanceTemplateListGet

Files

Req Y

Y

47

From Class

IFD

Req

InstanceExtListGet

Files

Y

InstanceFilterFlagsGet

Files

InstanceIsDirFlagsGet

Files

InstanceShortNameListGet

Files

Y

FileTitleIdentifyAndOpen

Files

Y

FileTitleIdentify

Files

FileDestroy

Files

FileOpen

Files

FileClose

Files

FileFlush

Files

FileModTimeGet

Files

FileCopy

Files

FileRename

Files

FileDataModTimeGet

Files

FileDataRead

Files

FileDataWrite

Files

FileDataDestroy

Files

InstanceCompressionTypesGet

RasterFormats

InstancePixelTypesGet

RasterFormats

InstanceLayerTypesGet

RasterFormats

InstanceRasterDataOrderTypesGet

RasterFormats

InstanceMapProjectionIsSupported

RasterFormats

FileLayerNamesGet

RasterFormats

FileLayerNamesSet

RasterFormats

FileRasterDataOrderGet

RasterFormats

FileRasterDataOrderSet

RasterFormats

FileCovarianceRead

RasterFormats

Y

Y

48

IFD

From Class

FileCovarianceWrite

RasterFormats

FileDependentGet

RasterFormats

FileDependentSet

RasterFormats

FileDependentLayerNameGet

RasterFormats

FileDependentLayerNameSet

RasterFormats

FileRasterFormatsNonStandardDataNamesGet

RasterFormats

LayerCreate

RasterFormats

LayerDestroy

RasterFormats

LayerOpen

RasterFormats

LayerClose

RasterFormats

LayerLayerTypeRead

RasterFormats

LayerLayerTypeWrite

RasterFormats

LayerRasterRead

RasterFormats

LayerRasterWrite

RasterFormats

LayerRasterModTimeGet

RasterFormats

LayerRasterReadInitiate

RasterFormats

LayerRasterReadCancel

RasterFormats

LayerRasterReadInitiate

RasterFormats

LayerRasterReadCancel

RasterFormats

LayerRasterNullValueRead

RasterFormats

LayerRasterNullValueWrite

RasterFormats

LayerRRDLayerNamesGet

RasterFormats

LayerRRDLayerNamesSet

RasterFormats

LayerScalarStatisticsRead

RasterFormats

LayerScalarStatisticsWrite

RasterFormats

LayerMapInfoRead

RasterFormats

LayerMapInfoWrite

RasterFormats

Req

Y

Y

49

IFD

From Class

LayerMapToPixelTransformRead

RasterFormats

LayerMapToPixelTransformWrite

RasterFormats

LayerMapProjectionRead

RasterFormats

LayerMapProjectionWrite

RasterFormats

LayerHistogramRead

RasterFormats

LayerHistogramModTimeGet

RasterFormats

LayerHistogramWrite

RasterFormats

LayerHistogramDestroy

RasterFormats

LayerContrastRead

RasterFormats

LayerContrastModTimeGet

RasterFormats

LayerContrastWrite

RasterFormats

LayerContrastDestroy

RasterFormats

LayerClassNamesRead

RasterFormats

LayerClassNamesModTimeGet

RasterFormats

LayerClassNamesWrite

RasterFormats

LayerClassNamesDestroy

RasterFormats

LayerColorRead

RasterFormats

LayerColorModTimeGet

RasterFormats

LayerColorWrite

RasterFormats

LayerColorDestroy

RasterFormats

LayerOpacityRead

RasterFormats

LayerOpacityModTimeGet

RasterFormats

LayerOpacityWrite

RasterFormats

LayerOpacityDestroy

RasterFormats

InstanceColumnTypesGet

DescriptorTables

TableOpen

DescriptorTables

TableCreate

DescriptorTables

Req

50

IFD

From Class

TableDestroy

DescriptorTables

TableClose

DescriptorTables

TableColumnNamesGet

DescriptorTables

TableColumnNamesSet

DescriptorTables

TableRowCountGet

DescriptorTables

TableRowCountSet

DescriptorTables

ColumnOpen

DescriptorTables

ColumnCreate

DescriptorTables

ColumnDestroy

DescriptorTables

ColumnClose

DescriptorTables

ColumnModTimeGet

DescriptorTables

ColumnDataRead

DescriptorTables

ColumnDataWrite

DescriptorTables

Req

51

Interface Function InstanceCompressionTypesGet Syntax long InstanceCompressionTypesGet( unsigned long *count, char ***compressionTypes )

/* Output */ /* Output */

Arguments

count Returns the number of supported compression types.

compressionTypes Returns an array of strings enumerating the supported compression types. Description The InstanceCompressionTypesGet function should return in *compressionTypes a list of compression types known to be supported for layers stored in the file format(s) supported by the DLL. If the DLL supports compressed and uncompressed data, the uncompressed option should be reflected in the returned list of compression types (normally as the list member “None”). If the DLL supports compression, the DLL side of the interface is responsible for decompression/compression of data. All callers of LayerRasterRead and LayerRasterWrite calls will be assuming a data format as described in the InstancePixelTypesGet function. This function should place a character string list in *compressionTypes which contains pointers to all compression name strings for files supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller.

count and compressionTypes can be assumed to be non-NULL. Return Value The function should return 0 for success and -1 for failure.

52

Requirements This function is optional. If this function does not exist, or if the function returns a NULL *compressionTypes list or a zero *count, the file format will be considered to support the single compression type “None”.

53

Interface Function InstancePixelTypesGet Syntax long InstancePixelTypesGet( unsigned long *count, char ***pixelTypes )

/* Output */ /* Output */

Arguments

count Returns the number of supported pixel types.

pixelTypes Returns an array of strings enumerating the supported pixel types. Description The InstancePixelTypesGet function should return in *pixelTypes a list of pixel types known to be supported for layers stored in the file format(s) supported by the DLL. If a pixel type other than the valid pixel types listed below is returned in the list, layers of that pixel type will be ignored. Pixel Type

Description

EMIF Equivalent

“u1”

Unsigned 1-bit

EMIF_T_U1

“u2”

Unsigned 2-bit

EMIF_T_U2

“u4”

Unsigned 4-bit

EMIF_T_U4

“u8”

Unsigned 8-bit

EMIF_T_UCHAR

“s8”

Signed 8-bit

EMIF_T_CHAR

“u16”

Unsigned 16-bit

EMIF_T_USHORT

“s16”

Signed 16-bit

EMIF_T_SHORT

“u32”

Unsigned 32-bit

EMIF_T_ULONG

“s32”

Signed 32-bit

EMIF_T_LONG

“f32”

Single precision floating point

EMIF_T_FLOAT

“f64”

Double precision floating point

EMIF_T_DOUBLE

54

Pixel Type

Description

EMIF Equivalent

“c64”

Single precision complex

EMIF_T_COMPLEX

“c128”

Double precision complex

EMIF_T_DCOMPLEX

It is the DLL’s responsibility both to convert each pixel into an appropriate internal representation when passing the data back to the caller of LayerRasterRead and to interpret the data correctly when receiving it from a LayerRasterWrite call. For purposes of doing this conversion/interpretation, the data format should conform to the description of the EMIF equivalent data type contained in Appendix B of the ERDAS Field Guide with the following exceptions: “u1”, “u2”, and “u4” data types should be expanded to occupy one byte per pixel “u16”, “s16”, “u32” and “s32” data types should be byte swapped relative to the ERDAS Field Guide description if the host platform of the DLL uses a Big Endian (Most Significant Byte First) byte order. This function should place a character string list in *pixelTypes which contains pointers to all pixel type strings for files supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. Return Value The function should return 0 for success and -1 for failure. Requirements This function is optional. If this function does not exist, or if the function returns a NULL *pixelTypes list or a zero *count, the file format will be considered to support the single pixel type “u8”.

55

Interface Function InstanceLayerTypesGet Syntax long InstanceLayerTypesGet( unsigned long *count, char ***layerTypes )

/* Output */ /* Output */

Arguments

count Returns the number of supported layer types.

layerTypes Returns an array of strings enumerating the supported layer types. Description The InstanceLayerTypesGet function should return in *layerTypes a list of layer types known to be supported for layers stored in the file format(s) supported by the DLL. If a layer type other than the recognized layer types listed below is returned, any layers with that layer type will be treated as “athematic” by the standard IMAGINE applications, although the correct layer type will be stored with and be accessible through the open Eimg_Layer. Layer Types “athematic” “thematic” “fft” For more information on layer types, refer to the LayerLayerTypeRead interface function definition. This function should place a character string list in *layerTypes which contains pointers to all layer type strings for files supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller.

56

Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional. If this function does not exist, or if the function returns a NULL *layerTypes list or a zero *count, the DLL will be assumed to support the single layer type “athematic”.

57

Interface Function InstanceRasterDataOrderTypesGet Syntax long InstanceRasterDataOrderTypesGet( unsigned long *count, char ***rdoTypes, unsigned char **rdoWriteFlags )

/* Output */ /* Output */ /* Output */

Arguments

count Returns the number of supported raster data order types.

layerTypes Returns an array of strings enumerating the supported raster data order types. Description The InstanceRasterDataOrderTypesGet function should return in *rdoTypes a list of raster data order types known to be supported for layers stored in the file format(s) supported by the DLL. The *rdoWriteFlags array should be set to an array of corresponding write flags that indicate whether the given raster data order type may be set on the file prior to layer creation so that it might be applied to the layers created (nonzero) or not (0). If the returned *rdoWriteFlags array is NULL, none of the returned raster data order types will be assumed to be able to be set on the file prior to layer creation. If a raster data order type other than the recognized layer raster data order types listed below is returned, any files with that raster data ordering will be treated as “BSQ” by the standard IMAGINE applications, although the correct raster data order type will be stored with and be accessible through the open Eimg_Layer Raster Data Order

Interpretation

BSQ

Band SeQuential

BIL

Band Interleaved by Line

BIP

Band Interleaved by Pixel

BSQC

Band SeQuential, Column major

58

Raster Data Order

Interpretation

BIC

Band Interleaved by Column

BIPC

Band Interleaved by Pixel, Column major

Mixed

No consistent ordering present

For more information on raster data order types, refer to the FileRasterDataOrderGet interface function definition. This function should place a character string list in *rdoTypes which contains pointers to all raster data order strings for files supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. If the function chooses to return an array in *rdoWriteFlags, this array should also be dynamically allocated so as to be freeable by the caller. Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional. If this function does not exist, or if the function returns a NULL *rdoTypes list or a zero *count, the DLL will be assumed to support the single raster data order type “BSQ”.

59

Interface Function InstanceMapProjectionIsSupported Syntax long InstanceMapProjectionIsSupported( long rfTitle, char *projTitle, unsigned char *MIFproj, unsigned long MIFprojSize, char *MIFprojDictionary, char *MIFprojName, unsigned char *MIFearthModel, unsigned long MIFearthModelSize, char *MIFearthModelDictionary, char *MIFearthModelName )

/* /* /* /* /* /* /* /* /* /*

Input Input Input Input Input Input Input Input Input Input

*/ */ */ */ */ */ */ */ */ */

Arguments

rfTitle Specifies the title index for the raster format for which support is being queried.

projTitle Specifies the projection title. MIFproj Specifies the MIF form of the projection. MIFprojSize Specifies the size of MIFproj in bytes. MIFprojDictionary Specifies the ASCII encoded MIF dictionary for MIFproj. MIFprojName Specifies the design name in MIFprojDictionary that describes MIFproj. MIFearthModel Specifies the earth model upon which the projection is based. MIFearthModelSize Specifies the size of MIFearthModel in bytes. MIFearthModelDictionary Specifies the ASCII encoded MIF dictionary for MIFearthModel.

60

MIFearthModelName Specifies the design name in MIFearthModelDictionary that describes MIFearthModel. Description The InstanceMapProjectionIsSupported should determine if the file format indicated by rfTitle can support the map projection described by the rest of the parameters. If the passed in projTitle is NULL, the DLL is being asked if rfTitle can support map projection deletion through the LayerMapProjectionWrite interface function (the remaining arguments are to be ignored in this case). Refer to the LayerMapProjectionRead interface function description for an explanation of how a map projection is represented for purposes of transfer across a DLL interface. Return Value This function should return 1 if the projection described is able to be stored in the format associated with rfTitle. Otherwise, zero should be returned. Requirements This function is optional. If the function does not exist and the DLL also provides a LayerMapProjectionWrite function, all map projections will be presumed to be writable to any format supported by the DLL Instance.

61

Interface Function FileLayerNamesGet Syntax long FileLayerNamesGet( void *fileHandle, unsigned long *count, char ***layerNames )

/* Input */ /* Output */ /* Output */

Arguments

fileHandle Specifies the open file from which to open a list of layer names. count Returns the number of image layers in fileHandle.

layerNames Returns a list of layer names for layers in fileHandle. Description The FileLayerNamesGet function returns a list of all of the layer names accessible in the file indicated by fileHandle. The value of *count should be set to reflect the number of layer names returned in the character string array, *layerNames.

fileHandle, layerNames, and count can be assumed to not be NULL. If *count is zero it will be interpreted as a successful search of the file that resulted in no layers of data being found. If *count is greater than zero, then *layerNames will be assumed to point to *count individually allocated NULL terminated ASCII character strings representing layer names. The layer names returned will normally not be full layer names, but simply the root of a full layer name as defined in the efnp package. Return Value This function should return 0 for success and -1 for failure. Requirements If this function does not exist, the DLL will be ignored for purposes of raster imagery access.

62

Interface Function FileLayerNamesSet Syntax long FileLayerNamesSet( void *fileHandle, unsigned long count, char **oldLayerNames, char **newLayerNames )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

fileHandle Specifies the open file in which to modify a list of layer names. count Specifies the number of layer names to be modified.

oldLayerNames Specifies count character strings representing the current names of the layers whose names are to be changed. newLayerNames Specifies count character strings representing the new names of the layers whose names are to be changed. Description The FileLayerNamesSet function should change the layer identifiers for the layers listed in oldLayerNames in file fileHandle to the layer identifiers listed in newLayerNames. The fileHandle, count, oldLayerNames, and newLayerNames parameters can all be assumed to be non-NULL. Requirements This function should return 0 for success and -1 for failure. Requirements This function is optional.

63

Interface Function FileRasterDataOrderGet Syntax long FileRasterDataOrderGet( void *fileHandle, unsigned long *order )

/* Input */ /* Output */

Arguments

fileHandle Specifies the open file from which to query the raster data order. order Returns the raster data order. Description The FileRasterDataOrderGet function returns the raster data ordering for the file indicated by fileHandle.

fileHandle and order can be assumed to not be NULL. *order should be set to the index into the raster data order types array returned by the InstanceRasterDataOrderTypesGet function. *order

Interpretation

BSQ

Band SeQuential

BIL

Band Interleaved by Line

BIP

Band Interleaved by Pixel

BSQC

Band SeQuential, Column major

BIC

Band Interleaved by Column

BIPC

Band Interleaved by Pixel, Column major

Mixed

No consistent ordering present

The “BIP” or “BIPC” raster data order is also appropriate if the raster data is tiled and the tiles for the various bands in the image file have been interleaved. The recognized designations are currently used only to control the order of processing of

64

blocks from the file. If the order is BIL/BIP/BIC/BIPC, the processing will occur on a block by block basis if possible. If the order is BSQ/BSQC, (or none of the above), the processing will occur on a layer by layer basis. If possible, blocks will be processed in column-major order for BSQC/BIC/BIPC, or in row-major order otherwise. Not all applications will respect the data order. Some applications will read layer by layer, even though the data is interleaved. The DLL should be prepared for such circumstances. Return Value This function should return 0 for success and -1 for failure. Requirements If this function does not exist, any image files supported by the DLL will be treated as if they are in band sequential order.

65

Interface Function FileRasterDataOrderSet Syntax long FileRasterDataOrderSet( void *fileHandle, unsigned long order, unsigned long count )

/* Input */ /* Input */ /* Input */

Arguments

fileHandle Specifies the open file in which to set the raster data order. order Specifies the raster data order.

count Specifies the number of layers of imagery about to be created in fileHandle. Description The FileRasterDataOrderSet function should set the raster data order on the file indicated by fileHandle to the order indicated by order. count will indicate the number of layers about to be created in the file. The fileHandle parameter can be assumed to be non-NULL and order can be assumed to be a valid index into the raster data order types array returned by the InstanceRasterDataOrderTypesGet function. The intent of this interface function is to allow data formats that support different raster data order to be informed about the intended raster data order immediately prior to initial image layer creation. It is not intended to allow raster data order to be modified after image layers already exist in fileHandle. Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional.

66

Interface Function FileCovarianceRead Syntax long FileCovarianceRead( void *fileHandle, char *name, unsigned long *count, double **covariance )

/* /* /* /*

Input */ Input */ Output */ Output */

Arguments

fileHandle Specifies the open file from which to obtain the covariance matrix. name Specifies the name of the covariance matrix to be obtained.

count Returns the number of image layers used to produce the covariance matrix.

covariance Returns the values representing the covariance matrix. Description The FileCovarianceRead function should read the covariance matrix named name from the file indicated by fileHandle.

fileHandle, name, count, and covariance can all be assumed to be non-NULL. The returned covariance array will be expected to contain *count X *count double values representing a covariance matrix produced for *count image layers. *covariance should be dynamically allocated so as to be freeable by the caller. Return Value This function should return 0 on success and -1 on failure. Any non-zero return value will be interpreted as failure. Requirements This function is optional.

67

Interface Function FileCovarianceWrite Syntax long FileCovarianceWrite( void *fileHandle, char *name, unsigned long count, double *covariance )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

fileHandle Specifies the open file from which to obtain the covariance matrix. name Specifies the name of the covariance matrix to be obtained.

count Specifies the number of image layers used to produce the covariance matrix.

covariance Specifies the values representing the covariance matrix. Description The FileCovarianceWrite function should write the covariance matrix named name to the file indicated by fileHandle.

fileHandle, name, count, and covariance can all be assumed to be non-NULL. covariance array will contain count X count double values representing a covariance matrix produced for count image layers. Return Value This function should return 0 on success and -1 on failure. Any non-zero return value will be interpreted as failure. Requirements This function is optional.

68

Interface Function FileDependentGet Syntax long FileDependentGet( char *fileHandle, char **dependentFileName )

/* Input */ /* Output */

Arguments

fileHandle Specifies the open file from which to query a dependent file name. dependentFileName Returns the dependent file name. Description The FileDependentGet function should obtain from fileHandle the name of the file for which fileHandle is serving to store auxiliary information (information not supported by the format implied by dependentFileName).

fileHandle and dependentFileName can be assumed to be non-NULL. This function should place a character string in *dependentFileName. The string should be dynamically allocated so as to be freeable by the caller. Return Value This function should return 0 on success and -1 on failure. Requirements This function is optional. This function is only required for DLL instances supporting formats that are intended to be used to store auxiliary data for formats that do not fully support all RasterFormats functionality.

69

Interface Function FileDependentSet Syntax long FileDependentSet( char *fileHandle, char *dependentFileName )

/* Input */ /* Input */

Arguments

fileHandle Specifies the open file in which to set a dependent file name. dependentFileName Specifies the dependent file name. Description The FileDependentSet function should establish in fileHandle the name of the file for which fileHandle is serving to store auxiliary information (information not supported by the format implied by dependentFileName).

fileHandle and dependentFileName can be assumed to be non-NULL. Return Value This function should return 0 on success and -1 on failure. Requirements This function is optional. This function is only required for DLL instances supporting formats that are intended to be used to store auxiliary data for formats that do not fully support all RasterFormats functionality.

70

Interface Function FileDependentLayerNameGet Syntax long FileDependentLayerNameGet( char *fileHandle, char *layerName, char **dependentLayerName )

/* Input */ /* Input */ /* Output */

Arguments

fileHandle Specifies the file handle from which to query a dependent layer name. layerName Specifies the layer name as known by fileHandle. dependentLayerName Returns the name by which fileHandle’s dependent file knows layerName. Description The FileDependentLayerNameGet function should obtain from fileHandle the name by which the layer layerName is known to fileHandle’s dependent file. This function will only be called in situations where fileHandle is serving to store auxiliary information for another file of a different format.

fileHandle, layerName, and dependentLayerName can be assumed to be non-NULL. This function should place a character string in *dependentLayerName. The string should be dynamically allocated so as to be freeable by the caller. Return Value This function should return 0 on success and -1 on failure. Requirements This function is optional. This function is only required for DLL instances supporting formats that are intended to be used to store auxiliary data for formats that do not fully support all RasterFormats functionality.

71

Interface Function FileDependentLayerNameSet Syntax long FileDependentLayerNameSet( char *fileHandle, char *layerName, char *dependentLayerName )

/* Input */ /* Input */ /* Input */

Arguments

fileHandle Specifies the file handle in which to set a dependent layer name. layerName Specifies the layer name as known by fileHandle. dependentLayerName Specifies the name by which fileHandle’s dependent file knows layerName. Description The FileDependentLayerNameSet function should establish in fileHandle the name by which the layer layerName is known to fileHandle’s dependent file. This function will only be called in situations where fileHandle is serving to store auxiliary information for another file of a different format.

fileHandle, layerName, and dependentLayerName can be assumed to be non-NULL. Return Value This function should return 0 on success and -1 on failure. Requirements This function is optional. This function is only required for DLL instances supporting formats that are intended to be used to store auxiliary data for formats that do not fully support all RasterFormats functionality.

72

Interface Function FileRasterFormatsNonStandardDataNamesGet Syntax long FileRasterFormatsNonStandardDataNamesGet( char *fileHandle, unsigned long *count, char ***dataNamesList )

/* Input */ /* Output */ /* Output */

Arguments

fileHandle Specifies the file from which to query non-standard data object names. count Returns the number of non-standard objects.

dataNamesList Returns a list of names for the non-standard objects. Description The FileRasterFormatsNonStandardDataNamesGet function should provide a list of names of data objects in fileHandle which are not related to the RasterFormats DLL Class. This list may be used to transfer these data objects to a different data source through the FileDataRead and FileDataWrite interface functions.

fileHandle, count, and dataNamesList can be assumed to be non-NULL. This function should place a character string list in *dataNamesList which contains pointers to names of all non-standard data objects in fileHandle. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. The number of items in the returned string list should be placed in *count. Return Value This function should return 0 on success and -1 on failure. Requirements This function is optional. If this function is provided, but the DLL Instance does not provide a FileDataRead function, this function will be ignored.

73

Interface Function LayerCreate Syntax long LayerCreate( void char unsigned long unsigned long unsigned long unsigned long unsigned long unsigned long void )

*fileHandle, **layerName, pType, width, height, compression, *bWidth, *bHeight, **layerHandle

/* /* /* /* /* /* /* /* /*

Input */ Output */ Input */ Input */ Input */ Input */ In/Out */ In/Out */ Output */

Arguments

fileHandle Specifies the file in which an image layer is to be created. layerName Returns the name of the newly created layer. pType Specifies the pixel type of the new layer.

width Specifies the width, in pixels, of the new layer.

height Specifies the height, in pixels, of the new layer.

compression Specifies the data compression to be used for the new layer. bWidth Suggests the block width to be used to access the layer and returns the block width that is actually to be used. bHeight Suggests the block height to be used to access the layer and returns the block height that is actually to be used. layerHandle

74

Returns a handle to the newly created layer. Description The LayerCreate function should attempt to create the layer of pixel type pType with dimensions width X height in the file represented by fileHandle. *layerName should be set to a point to a NULL terminated ASCII character string in the form of a root-relative representing the name of the new layer. For instance, if the DLL supports a three channel data format where the channels represent red, green and blue data values for an image, the DLL might want to set the layer name for the first layer created to “Red”, the second layer created to “Green”, and the third layer created to “Blue”. If any of the returned in the *layerName exceeds the length restrictions as described above, it will be truncated.

pType and compression can be expected to be valid indices into the lists returned by the InstancePixelTypesGet and InstanceCompressionTypesGet function calls, respectively. width and height can be expected to be non-zero values. *bWidth and *bHeight should be used as suggestions for the block width and block height of the layer. If the DLL supports tiles but cannot support the *bWidth and *bHeight suggested, it should modify the values passed in to the appropriate values for the DLL. If the data type does not support tiles at all, it should also set the *bWidth and *bHeight to some reasonable values (e.g., width, 1 to read in one row at a time). The raster data caching mechanism will use the *bWidth and *bHeight values to divide the image into blocks that may be cached. The DLL should set layerHandle to a value that can later be used to access the subobjects in this layer.

fileHandle can be assumed to be non-NULL. Return Value This function should return 0 upon success and -1 if an error occurs. If an error is returned by the LayerCreate function, the LayerClose function will NOT be called (the returned *layerHandle will be expected to be NULL). Requirements If this function is present, it will be ignored unless there is also a LayerDestroy function provided. This function is not required. If the DLL does not provide this function, new layers will not

75

be able to be created in this image format. Also, if this function is not present, the FileOpen function will never be called with any of the following fileMode’s (indicating that the file should be created): Mode

Description

“w” or “wb”

truncate to zero length or create for writing

“a” or “ab”

append; open for writing at end of file, or create for writing

“w+”, “w+b” or “wb+”

truncate or create for update''

“a+”, “a+b” or “ab+”

append; open or create for update at end-of-file

76

Interface Function LayerDestroy Syntax long LayerDestroy( void *fileHandle, char *layerName )

/* Input */ /* Input */

Arguments

fileHandle Specifies the file containing the layer to be destroyed. layerName Specifies the name of the layer to destroy in fileHandle. Description The LayerDestroy function should destroy the layer designated by fileHandle and layerName. If, after layer destruction, fileHandle is determined to have no layers remaining, the FileDestroy function may be called with the file name for fileHandle as an argument after fileHandle is closed with the FileClose call. Return Value The function should return 0 for success and -1 for failure (any non-zero return will be treated as failure). Requirements This function is optional.

77

Interface Function LayerOpen Syntax long LayerOpen( void char unsigned unsigned unsigned unsigned unsigned unsigned void )

long long long long long long

*fileHandle, *layerName, *pType, *width, *height, *compression, *bWidth, *bHeight, **layerHandle

/* /* /* /* /* /* /* /* /*

Input */ Input */ Output */ Output */ Output */ Output */ Output */ Output */ Output */

Arguments

fileHandle Specifies the file from which an image layer is to be opened. layerName Specifies the name of the image layer. pType Returns the pixel type of the layer.

width Returns the width, in pixels, of the layer.

height Returns the height, in pixels, of the layer.

compression Returns the data compression to used for the layer. bWidth Returns the block width to be used to access the layer. bHeight Returns the block height to be used to access the layer. layerHandle Returns a handle to the opened layer.

78

Description The LayerOpen function should attempt to open the layer designated by layerName in file fileHandle.

layerName will point to a NULL terminated ASCII character string representing the name of the layer to be opened. The DLL should set the pType, width, height and compression parameters. pType, and compression should be valid indices into the lists returned by the InstancePixelTypesGet and InstanceCompressionTypesGet function calls, respectively. width and height will be expected to be set to non-zero values. If the DLL supports tiles it should set the bWidth and bHeight to values appropriate for the tile size. If the data type does not support tiles at all, it should also set the *bWidth and *bHeight to some reasonable values (e.g., width, 1 to read in one row at a time). The raster data caching mechanism will use the bWidth and bHeight values to divide the image into blocks that may be cached. If the layer named layerName does not already exist, *layerHandle should be set to (void *)NULL and 0 should be returned (this is not considered an error). Return Value This function should return 0 upon success and -1 if an error occurs. If an error is returned by the LayerOpen function, the LayerClose function will NOT be called. Requirements This function must be defined by the DLL. Any DLL that does not have this function defined will be ignored even if it has a FileTitleIdentify function that confirms support of the file containing the layer.

79

Interface Function LayerClose Syntax long LayerClose( void *layerHandle )

/* Input */

Arguments

layerHandle Specifies the layer to close. Description The LayerClose function should perform all operations necessary to terminate processing on the opened layer represented by layerHandle. This might include freeing any temporary memory allocated for the layer and possibly closing related files. The operations that would result from a call to FileClose with an argument of the fileHandle used to generate the layerHandle should, in general, NOT be performed. Return Value This function should return 0 upon success and -1 if an error occurs. Requirements This function is optional but recommended. (Implementations choosing not to provide this function might defer all temporary memory deallocation until the file is closed).

80

Interface Function LayerLayerTypeRead Syntax long LayerLayerTypeRead( void *layerHandle, unsigned long *lType )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer to query for a layer type. lType Returns the layer type of layerHandle. Description The LayerLayerTypeRead function is used to find the layer type of an existing raster layer of data.

layerHandle and lType can be assumed to be non-NULL. The value returned in *lType should represent a valid index into the array returned by the InstanceLayerTypesGet function. If there is no layer type assigned to layerHandle, *lType should not be modified. Return Value A zero should be returned on success and a -1 on failure. Requirements This function is optional. If it is not provided, the layer type index will initially be assumed to be 0. This will correspond to an “athematic” layer if there is also no InstanceLayerTypesGet function provided by the DLL.

81

Interface Function LayerLayerTypeWrite Syntax long LayerLayerTypeWrite( void *layerHandle, unsigned long lType )

/* Input */ /* Input */

Arguments

layerHandle Specifies the layer in which the layer type is to be set. lType Specifies the layer type of layerHandle. Description The LayerLayerTypeWrite function is used to reset the layer type of an existing raster layer of data.

layerHandle can be assumed to be non-NULL. lType will represent a valid index into the array returned by the InstanceLayerTypesGet function. Return Value A zero should be returned on success and a -1 on failure. Requirements This function is optional.

82

Interface Function LayerRasterRead Syntax long LayerRasterRead( void unsigned long unsigned long unsigned char )

*layerHandle; bRow; bCol; **pixels;

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

layerHandle Specifies the layer from which raster data is to be read. bRow Specifies the block row of the block to be read.

bCol Specifies the block column of the block to be read.

pixels Returns the raster data for block bRow, bCol of layerHandle. Description The LayerRasterRead function should return from the layer indicated by layerHandle the pixels in the raster data block defined by bRow and bCol. When interpreting bRow and bCol, be aware that by convention, the block row and block column in the layer are indexed beginning with 0.

layerHandle can be assumed to be non-NULL. *pixels can be assumed to point to a memory area large enough to hold bWidth X bHeight X sizeof( pType ) bytes of data, where bWidth and bHeight are the block width and block height, respectively, as defined by the LayerCreate or LayerOpen call and pType is the pixel type of the data as defined by the LayerCreate or LayerOpen call. The DLL is responsible for properly padding partially filled blocks, i.e., ANY pixel value of the image, I(row,column), should be accessible via (*pixels)[(row % bHeight) * bWidth + column % bWidth] of the raster data block identified by bRow = row / bHeight and bCol = column / bWidth. This function can assume that bRow and bCol will always be specified such that the

83

resulting block intersects the valid image area (as defined by the width and height of the layer determined by the LayerCreate or LayerOpen call). Return Value The function should return 0 upon success and -1 on failure. If the block of raster data identified by bRow and bCol was never written to the file, *pixels should be set to NULL (this is not an error). Requirements This function must be defined by the DLL. Any DLL that does not have this function defined will be ignored even if it has a FileTitleIdentify function that confirms support of the file containing the layer.

84

Interface Function LayerRasterWrite Syntax long LayerRasterWrite( void *layerHandle, unsigned long bRow, unsigned long bCol, unsigned char *pixels )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

layerHandle Specifies the layer to which raster data is to be written. bRow Specifies the block row of the block to be written.

bCol Specifies the block column of the block to be written.

pixels Specifies the raster data for block bRow, bCol of layerHandle. Description The LayerRasterWrite function should store in the layer indicated by layerHandle the pixels in the raster data block defined by bRow and bCol. When interpreting bRow and bCol, be aware that by convention, the block row and block column in the layer are indexed beginning with 0.

layerHandle can be assumed to be non-NULL. pixels can be assumed to point to a memory block holding bWidth X bHeight X sizeof( pType ) bytes of data, where bWidth and bHeight are the block width and block height, respectively, as defined by the LayerCreate or LayerOpen call and pType is the pixel type of the data as defined by the LayerCreate or LayerOpen call. The DLL is responsible for extracting valid data from partially filled blocks (if necessary), i.e., ANY pixel value of the image, I(row,column), will be accessible via pixels[(row % bHeight) * bWidth + column % bWidth] of the raster data block identified by bRow = row / bHeight and bCol = column / bWidth. This function can assume that bRow and bCol will always be specified such that the

85

resulting block intersects the valid image area (as defined by the width and height of the layer determined by the LayerCreate or LayerOpen call). Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

86

Interface Function LayerRasterModTimeGet Syntax void LayerRasterModTimeGet( void *layerHandle, time_t *modTime )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer from which to obtain the raster modification time. modTime Returns the last modification time of the raster of layerHandle. Description The LayerRasterModTimeGet function should retrieve the time of the last modification to the raster data in the raster data layer indicated by layerHandle and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If raster data does not exist for the layer, (time_t)-1 should be placed in *modTime. (time_t is an ANSI C defined data type obtainable by including .)

layerHandle and modTime can be expected to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

87

Interface Function LayerRasterRectangleReadInitiate Syntax void LayerRasterRectangleReadInitiate( void *layerHandle, unsigned long bRow, unsigned long bCol, unsigned long bNumRows, unsigned long bNumCols )

/* /* /* /* /*

Input Input Input Input Input

*/ */ */ */ */

Arguments

layerHandle Specifies the layer for which raster data is about to be read. bRow Specifies the first row of blocks which are to be read.

bCol Specifies the first column of blocks which are to be read.

bNumRows Specifies the number of rows of blocks to be read. bNumCols Specifies the number of columns of blocks to be read. Description The LayerRasterRectangleReadInitiate function allows a DLL Instance to be informed of an impending read from layerHandle of the pixels in the raster data block defined by bRow and bCol. When interpreting bRow and bCol, be aware that by convention, the block row and block column in the layer are indexed beginning with 0.

layerHandle can be assumed to be non-NULL. Although a call to a DLL’s LayerRasterRectangleReadInitiate function should be taken by the DLL Instance as a hint that a call to LayerRasterRead will soon be made for the blocks within the specfied rectangle of blocks, it should not be taken as a guarantee that any such blocks will be read. In particular, the LayerRasterRead call may not occur prior to a LayerRasterWrite or LayerRasterRectangleReadCancel for the same rectangle of blocks and, in fact, the LayerRasterRead call may not occur at all prior to a LayerClose call in which layerHandle is passed as an argument.

88

LayerRasterRectangleReadInitiate may be called multiple times prior to the actual read of raster blocks. It is entirely typical for the DLL instance to receive one LayerRasterRectangleReadInitiate for the larger window being read by the application, and then a series of LayerRasterRectangleReadInitiate representing the smaller rectangles actually being read by the application. While the class owner will endeavor to follow the order specified by the FileDataOrderGet function, there is no guarantee that applications will respect this order. Return Value This function is of type void. By calling this function, the caller is simply informing the DLL Instance about likely impending events. The caller is unconcerned with what the DLL Instance does with this information. Requirements This function is optional. The LayerRasterRectangleReadCancel function should also be supplied by a DLL supplying this interface function so that the DLL can be informed about initiated reads that may not be satisfied through a call to LayerRasterRectangleRead or LayerRasterRectangleReadMIF.

89

Interface Function LayerRasterRectangleReadCancel Syntax void LayerRasterRectangleReadCancel( void *layerHandle, unsigned long bRow, unsigned long bCol, unsigned long bNumRows, unsigned long bNumCols )

/* /* /* /* /*

Input Input Input Input Input

*/ */ */ */ */

Arguments

layerHandle Specifies the layer for which initiated raster data reads are to be cancelled. bRow Specifies the first row of blocks for which an initiated read is to be cancelled.

bCol Specifies the first column of the blocks for which an initiated read is to be cancelled.

bNumRows Specifies the number of rows of blocks for which an initiated read is to be cancelled. bNumCols Specifies the number of columns of blocks for which an initiated read is to be cancelled. Description The LayerRasterRectangleReadCancel function allows a DLL Instance to be informed that the impending read from layerHandle of the blocks defined by bRow, bCol, bNumRows and bNumCols (possibly hinted at by a previous call to LayerRasterRectangleReadInitiate with the same arguments) has completed, or become less likely. Cancellation of one rectangle of blocks does not necessarily imply cancellation of any other initiated rectangle of blocks. When interpreting bRow and bCol, be aware that by convention, the block row and block column in the layer are indexed beginning with 0. An additional convention is that if bRow and bCol are both (unsigned long)-1, it should be taken by the DLL to be equivalent to having had LayerRasterRectangleReadCancel called for every block in the raster of the

90

layer associated with layerHandle.

layerHandle can be assumed to be non-NULL. Return Value This function is of type void. By calling this function, the caller is simply informing the DLL Instance about impending events that have become less likely. The caller is unconcerned with what the DLL Instance does with this information. Requirements This function is optional. This function will be ignored if there is no LayerRasterRectangleReadInitiate function supplied by the DLL Instance.

91

Interface Function LayerRasterReadInitiate Syntax void LayerRasterReadInitiate( void *layerHandle, unsigned long bRow, unsigned long bCol )

/* Input */ /* Input */ /* Input */

Arguments

layerHandle Specifies the layer for which raster data reads are to be initiated. bRow Specifies the block row of the block for which a read is to be initiated.

bCol Specifies the block column of the block for which a read is to be initiated. Description The LayerRasterReadInitiate function allows a DLL Instance to be informed of an impending read from layerHandle of the pixels in the raster data block defined by bRow and bCol. When interpreting bRow and bCol, be aware that by convention, the block row and block column in the layer are indexed beginning with 0.

layerHandle can be assumed to be non-NULL. Although a call to a DLL’s LayerRasterReadInitiate function should be taken by the DLL Instance as a hint that a call to LayerRasterRead will soon be made for the same bRow and bCol, it should not be taken as a guarantee that such a call will be made. In particular, the LayerRasterRead call may not occur prior to a LayerRasterWrite or LayerRasterReadCancel for the same bRow or bCol and, in fact, the LayerRasterRead call may not occur at all prior to a LayerClose call in which layerHandle is passed as an argument. This function will become obsolete (uncalled) if and when the asynchronous reading of data is moved to the eimg level so that all RasterFormats DLL Instances may benefit from asynchronous I/O simply by ensuring that they are thread safe. Return Value This function is of type void. By calling this function, the caller is simply informing the DLL

92

Instance about likely impending events. The caller is unconcerned with what the DLL Instance does with this information. Requirements This function is optional. The LayerRasterReadCancel function should also be supplied by a DLL supplying this interface function so that the DLL can be informed about initiated reads that may not be satisfied through a call to LayerRasterRead.

93

Interface Function LayerRasterReadCancel Syntax void LayerRasterReadCancel( void *layerHandle, unsigned long bRow, unsigned long bCol )

/* Input */ /* Input */ /* Input */

Arguments

layerHandle Specifies the layer for which initiated raster data reads are to be cancelled. bRow Specifies the block row of the block for which an initiated read is to be cancelled.

bCol Specifies the block column of the block for which an initiated read is to be cancelled. Description The LayerRasterReadCancel function allows a DLL Instance to be informed that the impending read from layerHandle of the pixels in the raster data block defined by bRow and bCol (possibly hinted at by a previous call to LayerRasterReadInitiate with the same arguments) has become less likely. When interpreting bRow and bCol, be aware that by convention, the block row and block column in the layer are indexed beginning with 0. An additional convention is that if bRow and bCol are both (unsigned long)-1, it should be taken by the DLL to be equivalent to having had LayerRasterReadCancel called for every block in the raster of the layer associated with layerHandle.

layerHandle can be assumed to be non-NULL. Return Value This function is of type void. By calling this function, the caller is simply informing the DLL Instance about impending events that have become less likely. The caller is unconcerned with what the DLL Instance does with this information. Requirements This function is optional. This function will be ignored if there is no

94

LayerRasterReadInitiate function supplied by the DLL Instance.

95

Interface Function LayerRasterNullValueRead Syntax long LayerRasterNullValueRead( void *layerHandle, unsigned char **pixel )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer from which to read the NULL value. pixel Returns the NULL value. Description The LayerRasterNullValueRead function should return from the layer indicated by layerHandle the pixel value representing NULL data in the layer raster. If a particular pixel has the NULL data value, no data will be considered to have been recorded for that pixel location. *pixel can be assumed to point to a memory area large enough to hold sizeof( pType ) bytes of data, where pType is the pixel type of the data as defined by the LayerCreate or LayerOpen call. If there is no null data value set in the file, *pixel should be set to NULL. Otherwise, the null data value should be copied into *pixel.

layerHandle can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

96

Interface Function LayerRasterNullValueWrite Syntax long LayerRasterNullValueWrite( void *layerHandle, unsigned char *pixel )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer in which to record the NULL value. pixel Specifies the NULL value. Description The LayerRasterNullValueWrite function should store in the layer indicated by layerHandle the pixel value, pixel, representing NULL data in the layer raster.

pixel can be assumed to point to a memory area holding sizeof( pType ) bytes of data, where pType is the pixel type of the data as defined by the LayerCreate or LayerOpen call. layerHandle can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

97

Interface Function LayerRRDLayerNamesGet Syntax long LayerRRDLayerNamesGet( void *layerHandle, unsigned long *count, char ***layerNames, char **algorithm )

/* /* /* /*

Input */ Output */ Output */ Output */

Arguments

layerHandle Specifies the layer from which to obtain an associated reduced resolution dataset. count Returns the number of layers in the reduced resolution dataset associated with layerHandle.

layerNames Returns a list of the full layer names of the image layers in the reduced resolution dataset associated with layerHandle. algorithm Returns the name of the algorithm used to compute the reduced resolution dataset associated with layerHandle. Description The LayerRRDLayerNamesGet function should return a list of layer names for the reduced resolution dataset (RRD) associated with this layer. A reduced resolution dataset is a set of image layers that represent layerHandle at varying resolutions (usually lower resolutions than layerHandle).

layerHandle, layerNames, algorithm, and count can all be assumed to be non-NULL. This function should place a character string list in *layerNames which contains pointers to full layer name strings (as described in the eimg API) for layers in the RRD of layerHandle. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. The number of string pointers residing at *layerNames should be placed in *count. The name of the algorithm used to compute the RRD (for informational purposes) should be placed in *algorithm. The algorithm name string should be dynamically allocated so as to be freeable by the caller.

98

Return Value The function should return 0 for success and -1 for failure. Requirements This function is optional.

99

Interface Function LayerRRDLayerNamesSet Syntax long LayerRRDLayerNamesSet( void *layerHandle, unsigned long count, char **layerNames, char *algorithm )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

layerHandle Specifies the layer with which to associated a reduced resolution dataset. count Specifies the number of layers in the reduced resolution dataset.

layerNames Specifies a list of the full layer names of the image layers in the reduced resolution dataset. algorithm Specifies the name of the algorithm used to compute the reduced resolution dataset. Description The LayerRRDLayerNamesSet function should record the list of layer names in the reduced resolution dataset (RRD) associated with this layer. Any previous RRD association should be discarded.

layerHandle can be assumed to be non-NULL. layerNames and count may be NULL if the RRD association is to be removed but not re-established. Return Value The function should return 0 for success and -1 for failure. Requirements This function is optional.

100

Interface Function LayerScalarStatisticsRead Syntax long LayerScalarStatisticsRead( void *layerHandle, double *minimum, double *maximum, double *mean, double *median, double *mode, double *stddev )

/* /* /* /* /* /* /*

Input */ Output */ Output */ Output */ Output */ Output */ Output */

Arguments

layerHandle Specifies the layer from which to retrieve image statistics. minimum Returns the minimum pixel value in layerHandle. maximum Returns the maximum pixel value in layerHandle. mean Returns the mean pixel value in layerHandle.

median Returns the median pixel value in layerHandle. mode Returns the modal pixel value in layerHandle.

stddev Returns the standard deviation for pixel values in layerHandle. Description The LayerScalarStatisticsRead function should read the relevant statistical information for the raster of the layer indicated by layerHandle. Before this function is called, *minimum, *maximum, *mean, *median, *mode, and *stddev will be set to a value in the IEEE 754 floating point standard quiet NaN class.

101

If any of the information cannot be returned, the values passed into the function call should be left unaltered. Return Value This function should return the count of the scalar statistics parameters that were altered on success and -1 on failure. A return of zero indicates the absence of statistical information but does not indicate an error. Requirements This function is optional.

102

Interface Function LayerScalarStatisticsWrite Syntax long LayerScalarStatisticsWrite( void *layerHandle, double *minimum, double *maximum, double *mean, double *median, double *mode, double *stddev )

/* /* /* /* /* /* /*

Input Input Input Input Input Input Input

*/ */ */ */ */ */ */

Arguments

layerHandle Specifies the layer in which to record image statistics. minimum Specifies the minimum pixel value in layerHandle. maximum Specifies the maximum pixel value in layerHandle. mean Specifies the mean pixel value in layerHandle.

median Specifies the median pixel value in layerHandle. mode Specifies the modal pixel value in layerHandle.

stddev Specifies the standard deviation for pixel values in layerHandle. Description The LayerScalarStatisticsWrite function should write the relevant statistical information to the layer indicated by layerHandle, ignoring any parameters it is unable to save. Return Value This function should return 0 on success and -1 on failure. Any non-zero return value will

103

be interpreted as failure. Requirements This function is optional.

104

Interface Function LayerMapInfoRead Syntax long LayerMapInfoRead( void *layerHandle, char **projection, double *xULC, double *yULC, double *xPixelSize, double *yPixelSize, char **units )

/* /* /* /* /* /* /*

Input */ Output */ Output */ Output */ Output */ Output */ Output */

Arguments

layerHandle Specifies the layer from which to read georeferencing information. projection Returns the name of the projection to which the layer is rectified. xULC Returns the x dimension of the map coordinate of layer pixel 0, 0.

yULC Returns the y dimension of the map coordinate of layer pixel 0, 0.

xPixelSize Returns the width of a pixel in the designated projection. yPixelSize Returns the height of a pixel in the designated projection. units Returns the units in which xULC, yULC, xPixelSize, and yPixelSize are specified. Description The LayerMapInfoRead function should return from the layer indicated by layerHandle the various georeferencing (how the pixels in the image layer relate to a projected geographic map system) parameters associated with the layer. The MapInfo model of georeferencing is a very simple model that requires that the imagery be rectified to the projected coordinate system. It also requires that the map

105

system coordinate axes not be rotated from the file coordinate axes, although reflection is representable by the sign on the pixel size parameters. If a more complicated model needs to be described, the LayerMapToPixelTransformRead function must be implemented. The pixel coordinate system should be understood to overlay the pixel grid in such a way that the center of each pixel in the grid is located at integral pixel coordinates. The diagram below depicts the relationship between the pixel grid, the pixel coordinate system and a standard map coordinate system associated with the pixel coordinate system for an example 3X3 pixel raster. (0,0)

(w-1,0)

c

y

x (w-1,h-1)

r Map System Axes

Pixel System Axes Overlaying Pixel Grid

Note that this implies that the bounding box for the image in pixel coordinates is {(-0.5,-0.5), (w-0.5,h-0.5)}. In this example, as in most cases of rectified imagery, the map coordinate system y-axis increases in a direction opposite the pixel coordinate system yaxis (labeled “r” for row), thereby necessitating that the returned yPixelSize be negative. The map projection and units names should be dynamically allocated NULL terminated ASCII strings of characters, pointers to which should be placed in *projection and *units respectively. To be most useful, these names should be names known by the eprj and ecvt API’s respectively, however, this is not required.

106

The map (x, y) location of file pixel 0, 0 should be placed in *xULC and *yULC respectively. The pixel width and height should be placed in *xPixelSize and *yPixelSize respectively.

layerHandle, projection, xULC, yULC, xPixelSize, yPixelSize, and units can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. If there is no map information found in the layer, the function arguments should be left unaltered and 0 should be returned (this is not considered failure). Requirements This function is optional. In order to deliver georeferencing information for a layer, a DLL may provide a LayerMapToPixelTransformRead function, a LayerMapInfoRead function, both or neither. If the DLL provides both the LayerMapToPixelTransformRead function and the LayerMapInfoRead function, the LayerMapToPixelTransformRead function will only be called if the LayerMapInfoRead function indicates (by leaving its function arguments unaltered) that the layer does not have a MapInfo style georeferencing.

107

Interface Function LayerMapInfoWrite Syntax long LayerMapInfoWrite( void *layerHandle, char *projection, double xULC, double yULC, double xPixelSize, double yPixelSize, char *units )

/* /* /* /* /* /* /*

Input Input Input Input Input Input Input

*/ */ */ */ */ */ */

Arguments

layerHandle Specifies the layer to which to write georeferencing information. projection Specifies the name of the projection to which the layer is rectified. xULC Specifies the x dimension of the map coordinate of layer pixel 0, 0.

yULC Specifies the y dimension of the map coordinate of layer pixel 0, 0.

xPixelSize Specifies the width of a pixel in the designated projection. yPixelSize Specifies the height of a pixel in the designated projection. units Specifies the units in which xULC, yULC, xPixelSize, and yPixelSize are specified. Description The LayerMapInfoWrite function should set in the layer indicated by layerHandle the various georeferencing parameters associated with the layer. Refer to the LayerMapInfoRead interface function definition for a description of the MapInfo model of georeferencing.

108

The map projection and units names will often be names known by the eprj and ecvt API’s respectively, however, this is not required. The map (x, y) location of file pixel 0, 0 is specified in xULC and yULC respectively. The pixel width and height is specified in xPixelSize and yPixelSize respectively.

layerHandle can be assumed to be non-NULL. If projection and units are NULL, this should be interpreted as an indication to destroy any georeferencing information present within the layer. Otherwise, projection and units will both be non-NULL and the passed georeferencing information should be recorded in the layer. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional. In order to record georeferencing information for a layer, a DLL may provide a LayerMapToPixelTransformWrite function, a LayerMapInfoWrite function, both or neither. If the DLL provides both the LayerMapToPixelTransformWrite function and the LayerMapInfoWrite function, the LayerMapToPixelTransformWrite function will only be called if the georeferencing information to be written cannot be represented as a MapInfo model.

109

Interface Function LayerMapToPixelTransformRead Syntax long LayerMapToPixelTransformRead( void *layerHandle, char **projection, char **units, long *count, char ***titles, unsigned char ***MIFxForms, unsigned long **MIFsizes, char ***MIFdictionaries, char ***MIFnames )

/* /* /* /* /* /* /* /* /*

Input */ Output */ Output */ Output */ Output */ Output */ Output */ Output */ Output */

Arguments

layerHandle Specifies the layer from which to read georeferencing information. projection Returns the name of the projection to which the layer is rectified. units Returns the units for the map coordinates expected by the returned map-to-pixel transformation.

count Returns the number of transformation components describing the map to pixel transformation.

titles Returns an array containing titles from the GeometricModels DLL Class, one for each transformation component.

MIFxForms Returns an array containing pointers to MIF versions of transformations, one for each transformation component. MIFsizes Returns an array containing the sizes, in bytes, of the MIF objects delivered in MIFxForms. MIFdictionaries 110

Returns an array containing the encoded MIF dictionaries of the MIF objects delivered in MIFxForms.

MIFnames Returns an array containing the names of the designs in MIFdictionaries that describe the MIFxForms. Description The LayerMapToPixelTransformRead function should return from the layer indicated by layerHandle the various georeferencing parameters associated with the layer. This function provides a more general and, therefore, more complex method of specifying georeferencing information than the LayerMapInfoRead interface function. The generalization is directed at the map to pixel transformation part of the georeferencing information. The method of specifying the map projection name and units is identical to the LayerMapInfoRead interface. A generalized transformation is represented as 1 or more transformation components. Each component must be supported by a title in the GeometricModels DLL Class. The MIF representation of the ith transformation component, as would be obtained by the XFormConvertToMIF interface function, is delivered via the ith entry of each of four returned arrays, MIFxForms, MIFsizes, MIFdictionaries, and MIFnames. The order of the array elements is significant, for it defines the order of application of the transformation components in order to achieve a map to pixel coordinate transformation. In other words, in order to achieve the map to pixel coordinate transformation, map coordinates can be passed as input to the XFormTransform function using the 0th transformation component, the output of that operation can be used as input to the XFormTransform function using the next transformation component, and so on until the XFormTransform function call using transform component (count-1) delivers pixel coordinates that correspond to the initial input map coordinates. Refer to the description of the LayerMapInfoRead interface function for a definition of how the pixel coordinate system overlays the pixel grid. The map projection and units names should be dynamically allocated NULL terminated ASCII strings of characters, pointers to which should be placed in *projection and *units respectively. To be most useful, these names should be names known by the eprj and ecvt API’s respectively, however, this is not required. The function should place the number of transformation components required for the map to pixel transformation in *count and return five dynamically allocated arrays (so as to be freeable by the caller) in *titles, *MIFxForms, *MIFsizes, *MIFdictionaries, and *MIFnames, each of which contain *count array elements. The individual array elements of the *titles, *MIFxForms, *MIFdictionaries and *MIFnames arrays should also be individually dynamically allocated so as to be freeable by the caller. Each transformation

111

component, then, should be able to be fully described through the five corresponding (same index) array elements in the returned arrays. All function arguments can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. If there is no georeferencing information present in the layer, *projection and *units should be set to NULL and the remaining arguments should be left unaltered. This is not considered an error. Requirements This function is optional. In order to deliver georeferencing information for a layer, a DLL may provide a LayerMapToPixelTransformRead function, a LayerMapInfoRead function, both or neither. If the DLL provides both the LayerMapToPixelTransformRead function and the LayerMapInfoRead function, the LayerMapToPixelTransformRead function will only be called if the LayerMapInfoRead function indicates (by leaving its function arguments unaltered) that the layer does not have a MapInfo style georeferencing.

112

Interface Function LayerMapToPixelTransformWrite Syntax long LayerMapToPixelTransformWrite( void *layerHandle, char *projection, char *units, long count, char **titles, unsigned char **MIFxForms, unsigned long *MIFsizes, char **MIFdictionaries, char **MIFnames )

/* /* /* /* /* /* /* /* /*

Input Input Input Input Input Input Input Input Input

*/ */ */ */ */ */ */ */ */

Arguments

layerHandle Specifies the layer to which to write georeferencing information. projection Specifies the name of the projection to which the layer is rectified. units Specifies the units for the map coordinates expected by the specified map-to-pixel transformation.

count Specifies the number of transformation components describing the map to pixel transformation.

titles Specifies an array containing titles from the GeometricModels DLL Class, one for each transformation component.

MIFxForms Specifies an array containing pointers to MIF versions of transformations, one for each transformation component. MIFsizes Specifies an array containing the sizes, in bytes, of the MIF objects passed in MIFxForms. MIFdictionaries 113

Specifies an array containing the encoded MIF dictionaries of the MIF objects passed in MIFxForms.

MIFnames Specifies an array containing the names of the designs in MIFdictionaries that describe the MIFxForms. Description The LayerMapToPixelTransformWrite function should set in the layer indicated by layerHandle the various georeferencing parameters associated with the layer. This function provides a more general and, therefore, more complex method of recording georeferencing information than the LayerMapInfoWrite interface function. Refer to the LayerMapToPixelTransformRead interface function definition for a detailed description of the generalization. The map projection and units names will often be names known by the eprj and ecvt API’s respectively, however, this is not required. The number of transformation components required for the map to pixel transformation is specified in count and the five arrays titles, MIFxForms, MIFsizes, MIFdictionaries, and MIFnames, each contain count array elements. Each transformation component, is fully described through the five corresponding (same index) array elements in the specified arrays.

layerHandle can be assumed to be non-NULL. If projection and units are non-NULL, count, titles, MIFxForms, MIFsizes, MIFdictionaries and MIFnames can all be assumed to be non-NULL. If projection and units are NULL, count, titles, MIFxForms, MIFsizes, MIFdictionaries and MIFnames should be ignored and this should be interpreted as an indication to destroy any georeferencing information present within the layer. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional. In order to record georeferencing information for a layer, a DLL may provide a LayerMapToPixelTransformWrite function, a LayerMapInfoWrite function, both or neither. If the DLL provides both the LayerMapToPixelTransformWrite function and the LayerMapInfoWrite function, the LayerMapToPixelTransformWrite function will only

114

be called if the georeferencing information to be written cannot be represented as a MapInfo model.

115

Interface Function LayerMapProjectionRead Syntax long LayerMapProjectionRead( void *layerHandle, char **projTitle, unsigned char **MIFproj, unsigned long *MIFprojSize, char **MIFprojDictionary, char **MIFprojName, unsigned char **MIFearthModel, unsigned long *MIFearthModelSize, char **MIFearthModelDictionary, char **MIFearthModelName )

/* /* /* /* /* /* /* /* /* /*

Input */ Output */ Output */ Output */ Output */ Output */ Output */ Output */ Output */ Output */

Arguments

layerHandle Specifies the layer from which a projection is to be read. projTitle Returns the projection title. MIFproj Returns the MIF form of the projection. MIFprojSize Returns the size of MIFproj in bytes. MIFprojDictionary Returns the ASCII encoded MIF dictionary for MIFproj. MIFprojName Returns the design name in MIFprojDictionary that describes MIFproj. MIFearthModel Returns the earth model upon which the projection is based. MIFearthModelSize Returns the size of MIFearthModel in bytes. MIFearthModelDictionary Returns the ASCII encoded MIF dictionary for MIFearthModel.

116

MIFearthModelName Returns the design name in MIFearthModelDictionary that describes MIFearthModel. Description The LayerMapProjectionRead function should return from the layer indicated by layerHandle the various geocoding (how a geographic projected map system is related to some model of the earth) parameters associated with the projection named in the georeferencing parameters associated with the layer (see LayerMapInfoRead and LayerMapToPixelTransformRead). Geocoding more fully describes the georeferencing of an image layer. It allows the image layer to be related to other image layers that are also georeferenced and geocoded, but that do not necessarily use the same geographic projected map system. Therefore, it does not make sense to seek out geocoding information from layers that are not georeferenced, nor does it make sense to store geocoding information with layers that are not georeferenced. All function parameters can be expected to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

117

Interface Function LayerMapProjectionWrite Syntax long LayerMapProjectionWrite( void *layerHandle, char *projTitle, unsigned char *MIFproj, unsigned long MIFprojSize, char *MIFprojDictionary, char *MIFprojName, unsigned char *MIFearthModel, unsigned long MIFearthModelSize, char *MIFearthModelDictionary, char *MIFearthModelName )

/* /* /* /* /* /* /* /* /* /*

Input Input Input Input Input Input Input Input Input Input

*/ */ */ */ */ */ */ */ */ */

Arguments

layerHandle Specifies the layer to which a projection is to be written. projTitle Specifies the projection title. MIFproj Specifies the MIF form of the projection. MIFprojSize Specifies the size of MIFproj in bytes. MIFprojDictionary Specifies the ASCII encoded MIF dictionary for MIFproj. MIFprojName Specifies the design name in MIFprojDictionary that describes MIFproj. MIFearthModel Specifies the earth model upon which the projection is based. MIFearthModelSize Specifies the size of MIFearthModel in bytes. MIFearthModelDictionary Specifies the ASCII encoded MIF dictionary for MIFearthModel.

118

MIFearthModelName Specifies the design name in MIFearthModelDictionary that describes MIFearthModel. Description The LayerMapProjectionWrite function should set in the layer indicated by layerHandle the various geocoding (see LayerMapProjectionRead) parameters associated with the projection named in the georeferencing parameters associated with the layer (see LayerMapInfoWrite and LayerMapToPixelTransformWrite).

layerHandle can be assumed to be non-NULL. If projTitle is non-NULL, MIFproj, MIFprojSize, MIFprojDictionary, MIFprojName, MIFearthModel, MIFearthModelSize, MIFearthModelDictionary, and MIFearthModelName can all be assumed to be non-NULL. If projTitle is NULL, MIFproj, MIFprojSize, MIFprojDictionary, MIFprojName, MIFearthModel, MIFearthModelSize, MIFearthModelDictionary, and MIFearthModelName should all be ignored and this should be interpreted as an indication to destroy any geocoding information present within the layer. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

119

Interface Function LayerHistogramRead Syntax long LayerHistogramRead( void *layerHandle, long startRow, long numRows, long *histogram )

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

layerHandle Specifies the layer from which a histogram is to be read. startRow Specifies the row of the table from which to begin reading data. numRows Specifies the number of rows to read. histogram Returns the read data. Description The LayerHistogramRead function should return from the layer indicated by layerHandle numRows rows of the layer histogram beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. histogram can be assumed to point to a memory area large enough to hold numRows X sizeof(long) bytes of data. This function is responsible for ensuring that the ith entry in the histogram array contains the number of pixels in the layer with the value startRow + i for 0 <= i < numRows. layerHandle and histogram can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Absence of a histogram should be considered failure.

120

Requirements This function is optional. This function will be ignored if the DLL does not also provide the LayerHistogramModTimeGet function.

121

Interface Function LayerHistogramModTimeGet Syntax long LayerHistogramModTimeGet( void *layerHandle, time_t *modTime )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer from which a data modification time is to be queried. modTime Returns the last modification time of the histogram indicated by layerHandle. Description The LayerHistogramModTimeGet function should retrieve the time of the last modification to the histogram associated with layerHandle and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the time of the last modification of the histogram cannot be obtained, setting *modTime to (time_t)0 is acceptable but may cause annoying (though not incorrect) application behavior. (time_t is an ANSI C defined data type obtainable by including .) If there is no histogram information for this layer, (time_t)-1 should be placed in *modTime.

layerHandle and modTime can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerHistogramRead function if either are to be used.

122

Interface Function LayerHistogramWrite Syntax long LayerHistogramWrite( void *layerHandle, long startRow, long numRows, long *histogram )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

layerHandle Specifies the layer to which a histogram is to be written. startRow Specifies the row of the table to which to begin writing data. numRows Specifies the number of rows to write. histogram Specifies the data to be written. Description The LayerHistogramWrite function should store in the layer indicated by layerHandle numRows rows of the layer histogram beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. histogram can be assumed to point to a memory area large enough to hold numRows X sizeof(long) bytes of data. This function is responsible for ensuring that the value of the histogram for row startRow + i that is stored in the layer associated with layerHandle contains the value histogram[i], for 0 <= i < numRows. layerHandle and histogram can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure.

123

Requirements This function is optional.This function will be ignored if the DLL does not also provide the LayerHistogramDestroy function.

124

Interface Function LayerHistogramDestroy Syntax long LayerHistogramDestroy( void *layerHandle )

/* Input */

Arguments

layerHandle Specifies a layer in which to destroy a histogram. Description The LayerHistogramDestroy function should destroy the histogram information in the image layer associated with layerHandle. Using the same layer, any subsequent calls to LayerHistogramModTimeGet that occur prior to a LayerHistogramWrite should return (time_t)-1.

layerHandle can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerHistogramWrite function if either are to be used. This function and the LayerHistogramWrite function will also be ignored if LayerHistogramRead and LayerHistogramModTimeGet are not both present.

125

Interface Function LayerContrastRead Syntax long LayerContrastRead( void *layerHandle, long startRow, long numRows, double *contrast )

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

layerHandle Specifies the layer from which contrast is to be read. startRow Specifies the row of the table from which to begin reading data. numRows Specifies the number of rows to read. contrast Returns the read data. Description The LayerContrastRead function should return from the layer indicated by layerHandle numRows rows of the layer contrast beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. contrast can be assumed to point to a memory area large enough to hold numRows X sizeof(double) bytes of data. This function is responsible for ensuring that the ith entry in the contrast array contains the contrast value for pixels in the layer with the value startRow + i for 0 <= i < numRows. Contrast values should be scaled so they range from 0.0 (minimum intensity) to 1.0 (maximum intensity). layerHandle and contrast can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Absence of contrast should be considered failure.

126

Requirements This function is optional. This function will be ignored if the DLL does not also provide the LayerContrastModTimeGet function.

127

Interface Function LayerContrastModTimeGet Syntax long LayerContrastModTimeGet( void *layerHandle, time_t *modTime )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer from which a data modification time is to be queried. modTime Returns the last modification time of the contrast indicated by layerHandle. Description The LayerContrastModTimeGet function should retrieve the time of the last modification to the contrast associated with layerHandle and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the time of the last modification of the contrast cannot be obtained, setting *modTime to (time_t)0 is acceptable but may cause annoying (though not incorrect) application behavior. (time_t is an ANSI C defined data type obtainable by including .) If there is no contrast information for this layer, (time_t)-1 should be placed in *modTime.

layerHandle and modTime can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerContrastRead function if either are to be used.

128

Interface Function LayerContrastWrite Syntax long LayerContrastWrite( void *layerHandle, long startRow, long numRows, double *contrast )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

layerHandle Specifies the layer to which contrast is to be written. startRow Specifies the row of the table to which to begin writing data. numRows Specifies the number of rows to write. contrast Specifies the data to be written. Description The LayerContrastWrite function should store in the layer indicated by layerHandle numRows rows of the layer contrast beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. contrast can be assumed to point to a memory area large enough to hold numRows X sizeof(double) bytes of data. This function is responsible for ensuring that the value of the contrast for row startRow + i that is stored in the layer associated with layerHandle contains the value contrast[i], for 0 <= i < numRows. Contrast values are scaled so they range from 0.0 (minimum intensity) to 1.0 (maximum intensity). layerHandle and contrast can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure.

129

Requirements This function is optional.This function will be ignored if the DLL does not also provide the LayerContrastDestroy function.

130

Interface Function LayerContrastDestroy Syntax long LayerContrastDestroy( void *layerHandle )

/* Input */

Arguments

layerHandle Specifies a layer in which to destroy contrast. Description The LayerContrastDestroy function should destroy the contrast information in the image layer associated with layerHandle. Using the same layer, any subsequent calls to LayerContrastModTimeGet that occur prior to a LayerContrastWrite should return (time_t)-1.

layerHandle can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerContrastWrite function if either are to be used. This function and the LayerContrastWrite function will also be ignored if LayerContrastRead and LayerContrastModTimeGet are not both present.

131

Interface Function LayerClassNamesRead Syntax long LayerClassNamesRead( void *layerHandle, long startRow, long numRows, char **classNames )

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

layerHandle Specifies the layer from which class names are to be read. startRow Specifies the row of the table from which to begin reading data. numRows Specifies the number of rows to read. classNames Returns the read data. Description The LayerClassNamesRead function should return from the layer indicated by layerHandle numRows rows of the layer class names beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. classNames can be assumed to point to a memory area large enough to hold numRows X sizeof(char *) bytes of data. This function is responsible for ensuring that the ith entry in the classNames array contains the class name value for pixels in the layer with the value startRow + i for 0 <= i < numRows. Class name values returned in the classNames array should be dynamically and individually allocated (so as to be freeable by the caller) NULLterminated ASCII character string pointers. layerHandle and classNames can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Absence of class names

132

should be considered failure. Requirements This function is optional. This function will be ignored if the DLL does not also provide the LayerClassNamesModTimeGet function.

133

Interface Function LayerClassNamesModTimeGet Syntax long LayerClassNamesModTimeGet( void *layerHandle, time_t *modTime )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer from which a data modification time is to be queried. modTime Returns the last modification time of the class names indicated by layerHandle. Description The LayerClassNamesModTimeGet function should retrieve the time of the last modification to the class names associated with layerHandle and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the time of the last modification of the class names cannot be obtained, setting *modTime to (time_t)0 is acceptable but may cause annoying (though not incorrect) application behavior. (time_t is an ANSI C defined data type obtainable by including .) If there are no class names in this layer, (time_t)-1 should be placed in *modTime.

layerHandle and modTime can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerClassNamesRead function if either are to be used.

134

Interface Function LayerClassNamesWrite Syntax long LayerClassNamesWrite( void *layerHandle, long startRow, long numRows, char **classNames )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

layerHandle Specifies the layer to which class names is to be written. startRow Specifies the row of the table to which to begin writing data. numRows Specifies the number of rows to write. classNames Specifies the data to be written. Description The LayerClassNamesWrite function should store in the layer indicated by layerHandle numRows rows of the layer class names beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. classNames can be assumed to point to a memory area large enough to hold numRows X sizeof(char *) bytes of data. This function is responsible for ensuring that the value of the class name for row startRow + i that is stored in the layer associated with layerHandle contains the string classNames[i], for 0 <= i < numRows. Class name values in the classNames array are NULL-terminated ASCII character string pointers. layerHandle and classNames can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure.

135

Requirements This function is optional.This function will be ignored if the DLL does not also provide the LayerClassNamesDestroy function.

136

Interface Function LayerClassNamesDestroy Syntax long LayerClassNamesDestroy( void *layerHandle )

/* Input */

Arguments

layerHandle Specifies a layer in which to destroy class names. Description The LayerClassNamesDestroy function should destroy the class names information in the image layer associated with layerHandle. Using the same layer, any subsequent calls to LayerClassNamesModTimeGet that occur prior to a LayerClassNamesWrite should return (time_t)-1.

layerHandle can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerClassNamesWrite function if either are to be used. This function and the LayerClassNamesWrite function will also be ignored if LayerClassNamesRead and LayerClassNamesModTimeGet are not both present.

137

Interface Function LayerColorRead Syntax long LayerColorRead( void *layerHandle, char *colorName, long startRow, long numRows, double *colorTable )

/* /* /* /* /*

Input */ Input */ Input */ Input */ Output */

Arguments

layerHandle Specifies the layer from which color table is to be read. colorName Specifies the name of the color to be read. startRow Specifies the row of the table from which to begin reading data. numRows Specifies the number of rows to read. colorTable Returns the read data. Description The LayerColorRead function should return from the layer indicated by layerHandle numRows rows of the layer color for color colorName beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. colorName can be expected to have the value “Red”, “Green”, or “Blue”. colorTable can be assumed to point to a memory area large enough to hold numRows X sizeof(double) bytes of data. This function is responsible for ensuring that the ith entry in the colorTable array contains the colorName color value for pixels in the layer with the value startRow + i for 0 <= i < numRows. Color values should be scaled so they range from 0.0 (minimum intensity) to 1.0 (maximum intensity).

138

layerHandle, colorName, and colorTable can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Absence of the color colorName should be considered failure. Requirements This function is optional. This function will be ignored if the DLL does not also provide the LayerColorModTimeGet function.

139

Interface Function LayerColorModTimeGet Syntax long LayerColorModTimeGet( void *layerHandle, char *colorName, time_t *modTime )

/* Input */ /* Input */ /* Output */

Arguments

layerHandle Specifies the layer from which a data modification time is to be queried. colorName Specifies the name of the color to be queried. modTime Returns the last modification time of color colorName indicated by layerHandle. Description The LayerColorModTimeGet function should retrieve the time of the last modification to the color, colorName, associated with layerHandle and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the time of the last modification of the color cannot be obtained, setting *modTime to (time_t)0 is acceptable but may cause annoying (though not incorrect) application behavior. (time_t is an ANSI C defined data type obtainable by including .) If there is no color information for color colorName in this layer, (time_t)-1 should be placed in *modTime.

layerHandle and modTime can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerColorRead function if either are to be used.

140

Interface Function LayerColorWrite Syntax long LayerColorWrite( void *layerHandle, char *colorName, long startRow, long numRows, double *colorTable )

/* /* /* /* /*

Input Input Input Input Input

*/ */ */ */ */

Arguments

layerHandle Specifies the layer to which a color table is to be written. colorName Specifies the name of the color to be written. startRow Specifies the row of the table to which to begin writing data. numRows Specifies the number of rows to write. colorTable Specifies the data to be written. Description The LayerColorWrite function should store in the layer indicated by layerHandle numRows rows of the layer color, colorName, beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. colorTable can be assumed to point to a memory area large enough to hold numRows X sizeof(double) bytes of data. This function is responsible for ensuring that the value of the color, colorName, for row startRow + i that is stored in the layer associated with layerHandle contains the value colorTable[i], for 0 <= i < numRows. Color values are scaled so they range from 0.0 (minimum intensity) to 1.0 (maximum intensity). colorName can be expected to have the value “Red”, “Green”, or “Blue”.

141

layerHandle, colorName, and colorTable can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.This function will be ignored if the DLL does not also provide the LayerColorDestroy function.

142

Interface Function LayerColorDestroy Syntax long LayerColorDestroy( void *layerHandle, char *colorName )

/* Input */ /* Input */

Arguments

layerHandle Specifies a layer in which to destroy a color table. colorName Specifies the name of the color to be destroyed. Description The LayerColorDestroy function should destroy the color information for color colorName in the image layer associated with layerHandle. Using the same layer and color, any subsequent calls to LayerColorModTimeGet that occur prior to a LayerColorWrite should return (time_t)-1.

layerHandle can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerColorWrite function if either are to be used. This function and the LayerColorWrite function will also be ignored if LayerColorRead and LayerColorModTimeGet are not both present.

143

Interface Function LayerOpacityRead Syntax long LayerOpacityRead( void *layerHandle, long startRow, long numRows, double *opacity )

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

layerHandle Specifies the layer from which opacity is to be read. startRow Specifies the row of the table from which to begin reading data. numRows Specifies the number of rows to read. opacity Returns the read data. Description The LayerOpacityRead function should return from the layer indicated by layerHandle numRows rows of the layer opacity beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. opacity can be assumed to point to a memory area large enough to hold numRows X sizeof(double) bytes of data. This function is responsible for ensuring that the ith entry in the opacity array contains the opacity value for pixels in the layer with the value startRow + i for 0 <= i < numRows. Opacity values should be scaled so they range from 0.0 (fully transparent) to 1.0 (fully opaque). layerHandle and opacity can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Absence of opacity should be considered failure.

144

Requirements This function is optional. This function will be ignored if the DLL does not also provide the LayerOpacityModTimeGet function.

145

Interface Function LayerOpacityModTimeGet Syntax long LayerOpacityModTimeGet( void *layerHandle, time_t *modTime )

/* Input */ /* Output */

Arguments

layerHandle Specifies the layer from which a data modification time is to be queried. modTime Returns the last modification time of the opacity indicated by layerHandle. Description The LayerOpacityModTimeGet function should retrieve the time of the last modification to the opacity associated with layerHandle and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the time of the last modification of the opacity cannot be obtained, setting *modTime to (time_t)0 is acceptable but may cause annoying (though not incorrect) application behavior. (time_t is an ANSI C defined data type obtainable by including .) If there is no opacity information for this layer, (time_t)-1 should be placed in *modTime.

layerHandle and modTime can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerOpacityRead function if either are to be used.

146

Interface Function LayerOpacityWrite Syntax long LayerOpacityWrite( void *layerHandle, long startRow, long numRows, double *opacity )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

layerHandle Specifies the layer to which opacity is to be written. startRow Specifies the row of the table to which to begin writing data. numRows Specifies the number of rows to write. opacity Specifies the data to be written. Description The LayerOpacityWrite function should store in the layer indicated by layerHandle numRows rows of the layer opacity beginning with row startRow.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows implied by the range of values afforded by the pixel type of layerHandle. opacity can be assumed to point to a memory area large enough to hold numRows X sizeof(double) bytes of data. This function is responsible for ensuring that the value of the opacity for row startRow + i that is stored in the layer associated with layerHandle contains the value opacity[i], for 0 <= i < numRows. Opacity values are scaled so they range from 0.0 (fully transparent) to 1.0 (fully opaque). layerHandle and opacity can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure.

147

Requirements This function is optional.This function will be ignored if the DLL does not also provide the LayerOpacityDestroy function.

148

Interface Function LayerOpacityDestroy Syntax long LayerOpacityDestroy( void *layerHandle )

/* Input */

Arguments

layerHandle Specifies a layer in which to destroy opacity. Description The LayerOpacityDestroy function should destroy the opacity information in the image layer associated with layerHandle. Using the same layer, any subsequent calls to LayerOpacityModTimeGet that occur prior to a LayerOpacityWrite should return (time_t)-1.

layerHandle can be assumed to be non-NULL. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional but it must accompany a LayerOpacityWrite function if either are to be used. This function and the LayerOpacityWrite function will also be ignored if LayerOpacityRead and LayerOpacityModTimeGet are not both present.

149

150

DLL Implementation grid DLL Class Membership RasterFormats Description The grid DLL implementation is provided to allow immediate access, creation, and update of ESRI GRIDs. The GRID data model is the primary method for representing raster data and its descriptive attributes in ARC/INFO. GRID Stacks A GRID stack is a set of 1 to 20 GRIDs that are all projected to the same coordinate system (a GRID with an UNKNOWN projection may be included in a stack). The map area of the stack is the area of intersection of all of the component GRIDs. When GRID access was first implemented in IMAGINE (Version 8.1) the design for this feature (a single sentence in the design document) did not specify how GRID stacks would be accommodated. For reasons known only to the person who implemented this access, a GRID stack was deemed to be an ASCII file that listed the GRIDs included in the stack. With the update of the grid DLL for layer creation, this pseudo-GRID stack definition was discovered and an additional title was added to support the real GRID stack while still providing access for the old, pseudo GRID stack. Table Access A major feature of a GRID coverage is its associated Value Attribute Table (VAT). The VAT is analogous to the image descriptor table in the IMAGINE architecture. Therefore, the grid DLL makes the VAT of a GRID accessible through the DescriptorTables interface (optionally inherited by the RasterFormats DLL Class). In terms of the IMAGINE notion of descriptor table binning, the VAT of a GRID is treated as being directly binned starting with the lowest value that occurs in the raster data. In order to allow the RasterFormats Class owner to coordinate rows of a GRID descriptor based on its VAT with rows of a descriptor table in an associated auxiliary file, the grid DLL makes its notion of the bin function available to the class owner through an implementation of the FileDataRead IFD. The proper way to represent the bin function of a GRID is as an explicit bin function. The reason for this is that values that do not occur as pixel values in the raster data do not have a corresponding entry in the VAT. Because of the current limitations of IMAGINE’s

151

explicit bin function support, however, the bin function is represented by the grid DLL as described above. This choice of bin function representation may cause minor confusion in applications that allow users to edit the descriptor table of an image format. There will appear to be rows in the descriptor table for pixel values that do not exist in the image and any attempted updates to these rows will simply be forgotten by the grid DLL. Because of the approach to binning taken by the GRID format, floating point GRIDs do not have an associated VAT. Representation of a bin function for 32-bit data is somewhat problematic in that it may cause an excessive amount of memory to be allocated in order to load the table into memory. (For example, if a 32-bit data source has 10 distinct data values, five of which are clustered around -1,000,000 and the other five of which are clustered around 1,000,000, the table would have to be represented using 2,000,000 rows). There is no good solution to this problem currently. In order to avoid this excessive allocation of memory (and the errors that would, no doubt, follow such an attempt), a preference is provided to allow limiting the maximum number of rows allowed in a table associated with a 32-bit data set. Library Problems Because of the dangers of making function calls using ARC/INFO SDL (ARC/INFO functions call exit() when they encounter situations that they cannot handle; this makes use of the libraries from a DLL extremely difficult), the grid DLL implementation goes above and beyond what might normally be expected in ensuring the validity of the data. This prevents abnormal process termination in some cases at the expense of increased code complexity and decrease in GRID access speed. This behavior can be modified through a preference. Interface Function Support Appropriate interface functions are provided both to access and update information relevant to the GRID file format. In addition to reading and writing raster data, the GRID DLL provides read/write access to map information, projection information, and image descriptor information. The image descriptor support is provided through the DescriptorTables interface, rather than through the easy layer table functions of the RasterFormats DLL Class. Although the GRID format provides the ability to store and modify individual layer names, this capability is currently not provided through the DLL because of differences in the notion of a valid layer name between the GRID format and the RasterFormats class owner.

152

IFD Implementation gridInstanceTitleListGet Description The gridInstanceTitleListGet function returns three titles: "GRID", "GRID Stack", "STK". These titles represent a single GRID coverage, an ASCII file containing the names of zero or more GRID coverages (possibly in different workspaces), and a GRID Stack (as defined by ARC/INFO), respectively.

153

IFD Implementation gridInstanceTemplateListGet Description The gridInstanceTemplateListGet function returns the following templates: "*.grid", "*.stk", "*.gridstk". The "*.grid" and "*.gridstk" templates are identified as pseudotemplates, as they represent formats that are contained in directories.

154

IFD Implementation gridInstanceExtListGet Description The gridInstanceExtListGet function returns the following extensions: ".grid", ".stk", ".gridstk".

155

IFD Implementation gridInstanceFilterFlagsGet Description The gridInstanceFilterFlagsGet function returns the following flags: 1, 1, 1.

156

IFD Implementation gridInstanceIsDirFlagsGet Description The gridInstanceIsDirFlagsGet function returns the following flags: 1, 0, 1. This indicates that "GRID" and "STK" images are directories and "GRID Stack" images are not.

157

IFD Implementation gridInstanceIsCreatableFlagsGet Description The gridInstanceIsCreatableFlagsGet function returns the following flags: 1, 1, 1. This indicates that each of the formats is creatable through the DLL.

158

IFD Implementation gridInstanceShortNameListGet Description The gridInstanceShortNameListGet function returns the following names: "grid", "stk", "gridstk".

159

IFD Implementation gridInstanceCompressionTypesGet Description The gridInstanceCompressionTypesGet function returns a single type of compression: "Default". This is technically different than "None" because integer data types are always compressed by the GRID libraries.

160

IFD Implementation gridInstanceLayerTypesGet Description The gridInstanceLayerTypesGet function returns two layer types: "athematic", "thematic".

161

IFD Implementation gridInstancePixelTypesGet Description The gridInstancePixelTypesGet function returns ten types of pixel data: "u1", "u2", "u4", "u8", "s8", "u16", "s16", "u32", "s32", "f32".

162

IFD Implementation gridInstanceColumnTypesGet Description The gridInstanceColumnTypesGet function returns three supported column types: "integer", "real", and "string".

163

IFD Implementation gridInstanceMapProjectionIsSupported Description The gridInstanceMapProjectionIsSupported function determines whether or not the supplied projection can be translated into ARC/INFO projection parameters.

164

IFD Implementation gridFileTitleIdentify Description The gridFileTitleIdentify uses gridFileTitleIdentifyAndOpen to identify the passed in file name.

165

IFD Implementation gridFileOpen Description The gridFileOpen function uses gridFileTitleIdentifyAndOpen to open the passed in file name. If the open mode specifies file creation, a "GRID Stack" file will be requested.

166

IFD Implementation gridFileTitleIdentifyAndOpen Description The gridFileTitleIdentifyAndOpen function identifies and/or opens existing GRIDs, GRID Stacks, and STKs. The function can also create these data formats when they do not exist. If an existing data source requires opening, the permissions on all files in the related GRID and INFO directories (as well as the directories themselves) are examined to ensure that they are sufficient to accommodate the requested file open mode. This behavior can be turned off by setting the "Perform Rigorous Permission Check" preference in the "GRID Image Files" category to "false". Attempting read operations on files that do not have read permission or attempting write operations on files that do not have write permission may cause the ARC/INFO SDL Libraries to exit, bringing down any application that is relying on this DLL. If a new data source is being created, this function will make sure that any GRID or STK name attempted to be used consists of all lower case letters (the function will return an error if it finds otherwise). The ARC/INFO SDL Libraries handle upper or mixed case names by converting them to all lower case. This sort of operation currently cannot be handled by the RasterFormats DLL Class, as the class owner has no way of knowing that the data source name has been modified by a lower level. This will cause any related files (.aux, .rrd, etc.) to be ignored the next time the data source is accessed (because the ancillary file names will not have been converted to lower case). When a data source is opened as a GRID Stack, the DLL silently maintains the corresponding STK. Likewise, when a data source is opened as a STK, the DLL silently maintains the corresponding GRID Stack.

167

IFD Implementation gridFileClose Description The gridFileClose function frees the passed in file handle. If the file was not opened as a "GRID", the function will also maintain the associated .stk file at this time (if necessary).

168

IFD Implementation gridFileLayerNamesGet Description The gridFileLayerNamesGet function returns layer names based on the underlying GRIDs, no matter if the file was opened as a "GRID", "GRID Stack", or "STK". If all of the GRIDs are in the same workspace (directory), the base name of the GRID is returned as the layer name. If they are in different directories (only possible with multi-layer files opened through "GRID Stack" access), the full path name of the GRID is returned as the layer name.

169

IFD Implementation gridFileCopy Description The gridFileCopy function copies the named data source.

170

IFD Implementation gridFileDestroy Description The gridFileDestroy function removes the named data source from the file system after performing its own rigorous file permission check (see gridFileTitleIdentifyAndOpen).

171

IFD Implementation gridFileModTimeGet Description The gridFileModTimeGet determines the last modification time of the named data source by examining the modification time of every file related to the data source (i.e., every file in every directory representing every related GRID coverage). Currently, the INFO directory is not examined for modification times.

172

IFD Implementation gridFileRename Description The gridFileRename function renames the named data source to the new name specified.

173

IFD Implementation gridFileDataRead Description The gridFileDataRead function is used to simulate a bin function for a layer of a GRID data source. The only object that this function will return is a bin function object. This will only happen if the object name implies a bin function object is being read AND the implied layer of the bin function object being read exists in the GRID data source AND the designated layer is not a floating point pixel type. If all these conditions hold, the min and max values of the VAT of the associated layer will be used to simulate a direct bin function that will be returned by this function. This simulation allows the class owner to coordinate the data in the VAT (returned as a descriptor table) with any data in a descriptor table in an associated .aux file.

174

IFD Implementation gridFileDataModTimeGet Description The gridFileDataModTimeGet function is used only to indicate the existence of a simulated bin function (see gridFileDataRead). If the bin function named ought to be simulated, (time_t)0 is returned, otherwise (time_t)-1 is returned.

175

IFD Implementation gridLayerCreate Description The gridLayerCreate function creates the newly specified GRID layer through the CellLyrCreate function. If the file is opened as a "GRID", layer creation will succeed only if there are not already layers in the "GRID" (i.e., this is a newly created file). If the layer is successfully created, it is named after the base name of the GRID. The place holding file (created when the file is opened) is moved to a temporary name and will be deleted when the file is closed. If the file is opened as a "GRID Stack" or "STK", and the layer is successfully created, it is named after the base name of the .stk or STK plus the characters "c", where indicates the index in the .stk or STK of the newly created layer (indexed from 1). This follows ESRI’s GRID naming convention when image files are imported using IMAGEGRID. If the file is opened as a "GRID Stack", "STK" maintenance will be performed (if possible). If the .stk base name is less than or equal to 9 characters, an STK will be created and the newly created GRID will be added to the STK. Likewise, if the file is opened as a "STK", "GRID Stack" maintenance will be performed. This involves maintaining a file that has the names of the GRID files listed.

176

IFD Implementation gridLayerDestroy Description The gridLayerDestroy function removes the specified layer using the CellLyrDelete function. If the file has been opened as a "GRID", this function must rename the temporary "GRID Stack" file created when the file was created or opened so that it has the same name as the GRID. This is required to ensure proper clean-up when a layer creation fails for a "GRID". If the file has been opened as a "GRID Stack" or a "STK", the appropriate "other title" maintenance will be performed.

177

IFD Implementation gridLayerOpen Description The gridLayerOpen function opens the named layer using CellLyrOpen, allocates a GridLayer, and populates it with the appropriate information to allow subsequent operations on the layer to occur successfully. In addition to the layer names returned by the gridFileLayerNamesGet function, this function will also accommodate additional layer names for backward compatibility with IMAGINE 8.2 and IMAGINE 8.3. If the file was opened as a "GRID" and the layer name requested is "GRID", the GRID layer will be opened and returned. If the file was opened as a "GRID Stack" and the layer name requested was :GRID where matches either the full path or base name of an existing GRID in the stack, the corresponding layer will be opened. Regardless of how the file was opened, if the layer name specified is of the form "Layer_" and is a valid index (from 1) into the list of available GRID names, the corresponding layer will be opened. These accommodations are required because file node lists (layer names) returned from previous versions of IMAGINE may exist in map compositions and other files that need to be accessed through the updated DLL. All other layer names will be treated as non-existent. The ARC/INFO SDL Libraries currently impose a maximum limit of 50 simultaneous open channels. As there is presently no attempt in the GRID DLL implementation to work around this limit, the maximum number of layers that can be simultaneously opened in any data source handled by this DLL is 50. The actual number may be less because this is a per process limitation, not a per data source limitation (e.g., if more than one GRID data source is opened, the maximum number of layers that may be opened in any one of the opened GRID data sources will be less than 50).

178

IFD Implementation gridLayerClose Description The gridLayerClose function closes the passed in layer using CellLyrClose and then frees the memory associated with the layer. Information modified on the layer that is independent of the raster data (e.g., projection) is updated at this time.

179

IFD Implementation gridLayerLayerTypeRead Description The gridLayerLayerTypeRead function returns the layerType value of the GridLayer (converted to the correct index for passage across the interface). Existing coverages are treated as thematic if they have an integer pixel type and contain one or more table columns other than "Histogram", "Contrast", "Breakpoints", "VALUE", or "COUNT".

180

IFD Implementation gridLayerRasterRead Description The gridLayerRasterRead function calls GetWindowRectangle to read the raster data from the specified layer.

181

IFD Implementation gridLayerRasterWrite Description The gridLayerRasterWrite function uses the PutWindowRectangle function to write the raster data to the specified GRID layer.

182

IFD Implementation gridLayerScalarStatisticsRead Description The gridLayerScalarStatisticsRead function returns the minimum, maximum, and, possibly, the mean and standard deviation of the cell values in the designated layer.

183

IFD Implementation gridLayerMapInfoRead Description The gridLayerMapInfoRead returns map information in the appropriate form. GRID data sources are always treated as having map information.

184

IFD Implementation gridLayerMapInfoWrite Description The gridLayerMapInfoWrite function stores the map information specified in the designated layer. The GRID coverage associated with the layer is updated with the new map information at the time the layer is closed.

185

IFD Implementation gridLayerMapProjectionRead Description The gridLayerMapProjectionRead function returns a map projection in the correct form if one is present for the designated layer and it can be converted from the ARC/INFO format to the format used internally in IMAGINE.

186

IFD Implementation gridLayerMapProjectionWrite Description The gridLayerMapProjectionWrite function stores the map projection specified in the designated layer. The GRID coverage associated with the layer is updated with the new map projection at the time the layer is closed, assuming a translation to the ARC/INFO format for projections can be found.

187

IFD Implementation gridLayerRasterModTimeGet Description The gridLayerRasterModTimeGet function attempts to determine the time of the last modification to the raster data for the designated layer. This modification time is found by using the maximum modification time of any file with a name beginning with "q0" or "w" under the GRID coverage directory of the GRID coverage associated with the layer.

188

IFD Implementation gridTableClose Description The gridTableClose function closes a table previously opened by a gridTableOpen function call.

189

IFD Implementation gridTableColumnNamesGet Description The gridTableColumnNamesGet function delivers the names of the columns of a table that has been opened in a GRID data source. The only tables that can be opened in a GRID data source are simulated descriptor tables and in these cases the names returned by this function will come directly from the column names in the VAT associated with the GRID coverage associated with the layer designated in the name of the table that was opened.

190

IFD Implementation gridTableOpen Description The gridTableOpen function is responsible for simulating the presence of a descriptor table in a GRID data source. A descriptor table will be simulated if the name of the table to be opened implies a descriptor table of a layer that is present in the GRID data source and the pixel type of that layer is not of a floating point type.

191

IFD Implementation gridColumnModTimeGet Description The gridColumnModTimeGet function returns the last modification time of the VAT of the table within which the designated column exists.

192

IFD Implementation gridColumnClose Description The gridColumnClose function does nothing. Its presence is required in order for the class owner to recognize the gridColumnOpen function. The memory associated with a column is freed when the last reference to the layer associated with the table in which the column resides is closed.

193

IFD Implementation gridColumnDataRead Description The gridColumnDataRead function returns the specified data for the specified opened column.

194

IFD Implementation gridColumnDataWrite Description The gridColumnDataWrite function stores the information necessary to update the named column with the specified data in the VAT associated with the designated table. This update will actually be attempted at the time the last reference to the layer associated with the table is closed.

195

IFD Implementation gridColumnOpen Description The gridColumnOpen function returns a handle to a column if the named column exists in the VAT of the table designated in the function call.

196

IFD Implementation gridColumnCreate Description The gridColumnCreate function will store information necessary to create the named column with the specified type in the VAT associated with the designated table. This creation will actually be attempted at the time the last reference to the layer associated with the table is closed. Currently there is no way to accommodate name restrictions on column names in the DescriptorTables DLL Class Description. Because of this, creating a column with a name that contains internal spaces will appear to succeed based on the return value of this function, but will actually fail when a modification to the VAT is attempted at the time the last reference to the layer associated with the table is closed.

197

IFD Implementation gridColumnDestroy Description The gridColumnDestroy function is not yet implemented and will always return an error. Its presence is required in order to force the class owner to recognize the gridColumnCreate function.

198

DLL Implementation tiff DLL Class Membership RasterFormats Description The tiff DLL implementation is provided to allow immediate access, creation, and update of Tagged Image File Format (TIFF) files from within the IMAGINE product. TIFF is a popular and flexible public domain raster file format, the specification for which is claimed by Adobe Systems, Inc. The tiff DLL implementation also recognizes the GeoTIFF extension to TIFF. According to the GeoTIFF Format Specification, Revision 1.0, "The GeoTIFF spec defines a set of TIFF tags provided to describe all ’Cartographic’ information associated with TIFF imagery that originates from satellite imaging systems, scanned aerial photography, scanned maps, digital elevation models, or as a result of geographic analysis." Refer to http://home.earthlink.net/~ritter/geotiff/geotiff.html as a starting point for additional information on both TIFF and GeoTIFF. Baseline TIFF The tiff DLL implementation supports TIFF Revision 6.0. The support for TIFF Revision 6.0 is based on routines in LIBTIFF, Version 3.4 Beta 037, Copyright (c) 1988-1995 Sam Leffler, Copyright (c) 1991-1995 Silicon Graphics, Inc. At a minimum, the intent is to support Baseline TIFF as defined by the Revision 6.0 specification. In general, any requirement of Baseline TIFF that is not specifically addressed in this document is assumed to be implemented by LIBTIFF and it is thought that the use of LIBTIFF by this DLL implementation will fulfill the requirement. Implementation specific details are outlined below in a manner that matches the sectioning of the TIFF Revision 6.0 specification. TIFF Structure The Image File Header is used to identify the file as a TIFF file (see tiffFileTitleIdentifyAndOpen). All Image File Directories (IFDs) other than the first one in the file are ignored by the tiff DLL, as it is not required for a Baseline TIFF reader. Bilevel Images

199

Color If the PhotometricInterpretation tag indicates that WhiteIsZero, the pixel values are inverted prior to returning them through the tiffLayerRasterRead function. Compression The "No compression" option is the only option that specifically needs to be addressed by the tiff DLL implementation since the other compression options are handled through use of existing routines in LIBTIFF. Specifically, for BitsPerSample values less than 8, the data need to be unpacked into 1 pixel per byte prior to returning the data from the tiffLayerRasterRead function call. Conversely, the data need to be packed by the tiffLayerRasterWrite function call in the same situations. Physical Dimensions In the absence of any GeoTIFF information, the ResolutionUnit, XResolution, and YResolution values are considered and represented in the information returned from the tiffLayerMapInfoRead function. Grayscale Images No special implementation notes. Palette-color Images The ColorMap values in the image are converted to/from the TIFF defined range of 0 through 65535 from/to the IMAGINE defined range of 0.0 through 1.0 when they are written/read. RGB Full Color Images All layers of the full resolution image are made accessible by using the SamplesPerPixel value as the number of layers in the image. Additional Baseline TIFF Requirements Since the tiff DLL implementation provides update capabilities, it is essentially functioning within the IMAGINE product as a TIFF Editor. As such, the recommendations of the TIFF specification for TIFF Editors have been followed. Namely, a TIFF file modified in any way by the IMAGINE product will have any and all subfiles eliminated. Additionally, modifying the file in IMAGINE will cause all unrecognized fields (non-Baseline fields) to

200

also be eliminated from the TIFF file. This behavior can have serious consequences to a user’s data. Therefore, the default behavior of the tiff DLL is to open all TIFF images with read-only access, regardless of the user’s permissions on the file. The editing capabilities of the tiff DLL may be enabled by setting the "TIFF Image Files"/ "Edits Allowed" preference to "true". Another preference, "Unknown Tags", allows the user to choose to copy unknown tags using simply their field description. In the case where the user chooses to copy unknown tags asis, they should be made aware that (unrecognized) copied tags and data may be inconsistent with other modifications to the file. Baseline Field Reference Guide Artist Not accessed except to copy over. BitsPerSample Used to determine the pixel type for a layer. Images with a BitsPerSample value greater than 16 cannot have a color table stored for them and, thus, IMAGINE will not be able to remember that they are thematic. Therefore, LayerLayerTypeWrite is not be implemented. CellLength Not accessed except to copy over. CellWidth Not accessed except to copy over. ColorMap See Palette-color Images. Compression See Bilevel Images. Copyright Not accessed except to copy over. DateTime

201

Not accessed except to copy over. ExtraSamples Used to support multi-spectral imagery. FillOrder Not accessed and not copied over. Supported by LIBTIFF during the reading and writing of tiles and encoded strips. FreeByteCounts Not accessed and not copied over. FreeByteOffsets Not accessed and not copied over. GrayResponseCurve Not accessed except to copy over. GrayResponseUnit Not accessed except to copy over. HostComputer Not accessed except to copy over. ImageDescription Not accessed except to copy over. ImageLength Used as the layer height for all layers derived from a given subfile. ImageWidth Used as the layer width for all layers derived from a given subfile. Make Not accessed except to copy over. MaxSampleValue Used as the maximum image value for data of 16 bits and less.

202

MinSampleValue Used as the minimum image value for data of 16 bits and less. Model Not accessed except to copy over. NewSubfileType Not accessed except to copy over since only the first subfile is accessed and it must have a subfile type of 0. Orientation Used in conjunction with XResolution, YResolution and ResolutionUnit in simulating map information if no GeoTIFF information is present. PhotometricInterpretation Used as discussed above. PlanarConfiguration Used to determine if BIP data needs to be re-arranged prior to being returned across the tiffLayerRasterRead interface. ResolutionUnit See Orientation. By default, the DLL sets this tag explicitly to 1 (no absolute unit) when creating images. RowsPerStrip Used as the block height for non-tiled images. SamplesPerPixel Used as the number of layers in the image. Multi-spectral imagery (greater than three bands) is stored as extra samples of unknown data. Software Not accessed except to copy over. StripByteCounts

203

Used implicitly in reading and writing data through LIBTIFF. StripOffsets Used implicitly in reading and writing data through LIBTIFF. SubfileType Not accessed and not copied over. Threshholding Not accessed except to copy over. XResolution See Orientation. YResolution See Orientation. PackBits Compression Implemented through LIBTIFF. Modified Huffman Compression Implemented through LIBTIFF. TIFF Extensions Support for defined extensions of TIFF is enabled where support is provided in LIBTIFF. In instances where additional licensing is required, such as access to LZW compressed data, access through LIBTIFF has been controlled, but not disabled. Implementation specific details are outlined below in a manner that matches the sectioning of the TIFF Revision 6.0 specification. CCITT Bilevel Encodings Implemented through LIBTIFF. Document Storage and Retrieval All associated tags are not accessed except to copy over. LZW Compression Implemented through LIBTIFF. Access controlled during

204

tiffLayerRasterRead (denied if LZW license not present). Differencing Predictor Implemented through LIBTIFF in conjunction with LZW Compression. Tiled Images Implemented through LIBTIFF. Tile width and tile height used for block width and block height of layers. The "TIFF Image Files"/"Create Tiled Images" preference controls how new TIFF files are created from the DLL, since there is no opportunity to prompt the user. CMYK Images Implemented through LIBTIFF. No attempt is made to perform a color space conversion to RGB for return. Associated tags are not accessed except to copy over. HalftoneHints All associated tags are not accessed except to copy over. Associated Alpha Handling All associated tags are not accessed except to copy over. Data Sample Format This extension is used to support signed integer data types as well as floating point images. The SMinSampleValue and SMaxSampleValue tags are used in a manner similar to MinSampleValue and MaxSampleValue when dealing with data that is greater than 16 bits. RGB Image Colorimetry Associated tags are not accessed except to copy over. YCbCr Images Digital video format. All associated tags are not accessed except to copy over. As with CMYK, no attempt is made to perform a color space conversion to RGB for return. JPEG Compression Implemented through LIBTIFF. CIE L*a*b* Images

205

Implemented through LIBTIFF. As with CMYK, no attempt is made to perform a color space conversion to RGB for return. GeoTIFF The RasterFormats interface functions that relate to georeferencing and geocoding in the tiff DLL implementation were developed to support GeoTIFF Revision 1.0. The support for GeoTIFF Revision 1.0 is based on the final 1.0 release version of the platformindependent public-domain subroutine library for such purpose, Copyright (c) 1995 Niles D. Ritter. GeoTIFF divides the cartographic information associated with a TIFF image into two pieces: georeferencing and geocoding. This maps closely to IMAGINE’s MapInformation and Projection but there are some differences that need to be handled. Georeferencing GeoTIFF defines georeferencing as tying the raster space of an image to a model space (a map system). The georeferencing information is represented in three TIFF tags: ModelTiepointTag, ModelPixelScaleTag, and ModelTransformationTag. If ModelTiepointTag indicates that there is one tie point and the ModelPixelScaleTag is present, a MapInfo model is simulated. If the ModelTransformationTag is present, an Affine model is created from the transformation information. In the case where the ModelTiepointTag is present but the ModelPixelScaleTag is not, the "TIFF Image Files"/"Approximate Tie Points with a Polynomial" preference controls whether this image will be treated as georeferenced or not (a preference value of TRUE will allow the image to be treated as georeferenced). GeoTIFF has a notion of Raster Space which defines how the raster coordinate system grid lines lie with respect to the center of the pixel values in the image. The approach used in IMAGINE is analogous to the PixelIsPoint Raster Space of GeoTIFF, i.e., the grid lines of the raster coordinate system intersect at the center of the pixel. Therefore, an adjustment to the georeferencing information is always made if the PixelIsArea Raster Space is indicated in the GeoTIFF parameters so that IMAGINE applications will act on the georeferencing information correctly. When creating the information in a TIFF file, the PixelIsArea Raster Space is always used. Notably missing from the georeferencing information in the GeoTIFF

206

scheme is the model (map system) name and the units with which the georeferencing information is specified. This poses a problem for the tiff DLL because some IMAGINE applications allow georeferencing without geocoding. In the GeoTIFF scheme, both the units and the model name are deduced from the geocoding information. When this information cannot be produced, the units and model name must be remembered in a citation associated with one of the GeoTIFF keys. Geocoding GeoTIFF defines geocoding as tying coordinates in a model space to locations on the earth. Geocoding information is stored in a "MetaTag" (GeoKey) approach, a system of tagging that allows dozens of information elements to be encoded using just three TIFF tags. GeoTIFF uses GeoKeys to define projection types, coordinate systems, datums, ellipsoids, etc. so that geocoding a TIFF image is possible. These GeoKeys were derived from the EPSG list compiled by the Petrotechnical Open Software Corporation (POSC). Converting this geocoding information to/from something that can be used in IMAGINE is a straightforward, albeit massive, translation task. One issue already touched on is the fact that the geocoding information holds the units for the georeferencing information. When a standard projected coordinate system is used, the units are implied by this standard projected coordinate system. These implied units come from the tables of EPSG/POSC information referred to above. Because of this, a dilemma arises in translating georeferencing and geocoding information defined in IMAGINE to a TIFF file: should an otherwise standard projection be decomposed into appropriate user defined projection codes so that the nonstandard units of georeferencing may be retained, or should the standard projection code be used and the georeferencing information be altered to reflect the implied standard units? To solve this dilemma, it is left to the user to set the "TIFF Image Files"/"Geocoding preserves..." to either "Georeferencing Units" or "Standard Projections" as desired. DEM Data The ModelTiePointTag and ModelPixelScaleTag contain offset and scale information for DEM data that is currently ignored. ARC/INFO World File In the absence of GeoTIFF keys and prior to falling back on the device space information, the tiff DLL optionally searches for a world file associated with the TIFF file and uses any

207

information found as the georeferencing of the image. The optional access and maintenance of the world file by this DLL is controlled through the "TIFF Image Files"/ "World File Access" preference. The world file is incapable of storing map system name or unit name information, and it provides georeferencing information only (not geocoding). Interface Function Support Appropriate interface functions are provided both to access and update information relevant to the TIFF file format. The main data items that are accessible include the raster data, georeferencing information, geocoding information, and a color table.

208

IFD Implementation tiffInstanceTitleListGet Description The tiffInstanceTitleListGet function returns a single title: "TIFF".

209

IFD Implementation tiffInstanceTemplateListGet Description The tiffInstanceTemplateListGet function returns a single template: "*.tif".

210

IFD Implementation tiffInstanceExtListGet Description The tiffInstanceExtListGet function returns a single extension: ".tif".

211

IFD Implementation tiffInstanceShortNameListGet Description The tiffInstanceShortNameListGet function returns a single name: "tif".

212

IFD Implementation tiffInstanceCompressionTypesGet Description The tiffInstanceCompressionTypesGet function returns eight types of compression: "Default", "None", "CCITT (1D)", "CCITT Group 3", "CCITT Group 4", "LZW", "JPEG", "PackBits". The raster data of images using "LZW" compression is not accessible unless the LZW license is present. The "None", "CCITT (1D)", and "PackBits" compression types are required by Baseline TIFF. The "Default" type is supplied so that the compression type can be set by the user’s preferences in situations where they do not have the opportunity to explicitly name the compression type. The remaining types are accessible by virtue of LIBTIFF’s implementation of the following defined extensions: CCITT Bilevel Encodings, LZW Compression, and JPEG Compression. The CCITT compressions are intended for fax transmission and are only appropriate for binary data.

213

IFD Implementation tiffInstanceLayerTypesGet Description The tiffInstanceLayerTypesGet function returns two layer types: "athematic", "thematic". Any sample (layer) within a TIFF image with a valid color table is treated as "thematic". All others are treated as "athematic".

214

IFD Implementation tiffInstancePixelTypesGet Description The tiffInstancePixelTypesGet function returns ten types of pixel data: "u1", "u4", "u8", "s8", "u16", "s16", "u32", "s32", "f32", "f64". The TIFF specification does not preclude the "u2" data type, but it is not standard and is not easily supportable through the public domain library. Complex data could also be represented in a TIFF file, but the method of doing so (setting the SAMPLE_FORMAT tag to Other) would make the data useless/ uninterpretable for any application other than this DLL.

215

IFD Implementation tiffInstanceIsCreatableFlagsGet Description The tiffInstanceIsCreatableFlagsGet function returns the following flag: 1. This indicates that the format is creatable through the DLL.

216

IFD Implementation tiffInstanceMapProjectionIsSupported Description The tiffInstanceMapProjectionIsSupported function determines whether there is a GeoTIFF translation implemented for the passed projection.

217

IFD Implementation tiffFileTitleIdentifyAndOpen Description The tiffFileTitleIdentifyAndOpen function identifies, opens, and creates TIFF files. Identification of a TIFF file is based on determining if the file specified begins with the magic number of a TIFF file. This magic number is either "MM\000\052" or "II\052\000". The tiffFileTitleIdentifyAndOpen function uses the etif_Open function to open a TIFF file. The XTIFFOpen is used directly to create a TIFF file. Because the TIFF file format and its supporting public domain libraries are not geared toward editing, when a TIFF file is opened for creation or modification, most auxiliary information is cached in memory and raster data is dumped to a temporary file in IMG file format. Writing of the TIFF file actually takes place when the file is closed.

218

IFD Implementation tiffFileClose Description The tiffFileClose function frees the passed in file handle through an etif_Close function call. During this function call, any modifications to the file are performed by copying the original TIFF file over and updating those items that have changed or been added. If significant raster edits have been made (e.g., the file has been created), there may be a delay in closing the file while the raster data is copied from the temporary file within which it was cached.

219

IFD Implementation tiffFileLayerNamesGet Description The tiffFileLayerNamesGet function produces layer names of the form "Layer_" for all i from 1 to n, where n is the number of layers in the TIFF file as determined by the etif_Open function. The etif_Open function uses the TIFFTAG_SAMPLESPERPIXEL, if present, as the number of layers in the TIFF file. If this tag is not present, the etif_Open function examines the TIFFTAG_PHOTOMETRIC tag. If the tag indicates ETIF_RGB or ETIF_YCBCR, the number of layers will be three. If the tag indicates ETIF_CMYK, the number of layers will be four. Otherwise, the number of layers will be one.

220

IFD Implementation tiffFileCopy Description The tiffFileCopy function copies the TIFF source to the destination, including any associated world file. The TIFF world file is a file containing map information. It is not part of the GeoTIFF specification, but it is in common use due to its support by the ESRI product offering.

221

IFD Implementation tiffFileDestroy Description The tiffFileDestroy function removes the specified TIFF file and any associated world file from the file system. The TIFF world file is a file containing map information. It is not part of the GeoTIFF specification, but it is in common use due to its support by the ESRI product offering.

222

IFD Implementation tiffFileFlush Description The tiffFileFlush function is present so that the proper modification time of the TIFF file can be set. When this function is called, it records the time so that, after the TIFF file is closed, the time stamp on the file may be updated to reflect the actual time of the last change to the file. Without this function, any associated reduced resolution data sets are treated as out of date by the class owner because the modification time of the TIFF file will appear to be later than the creation of the reduced resolution data sets (since the TIFF file will not be closed until after the reduced resolution data sets have been computed).

223

IFD Implementation tiffFileRename Description The tiffFileRename function renames the specified TIFF file and any associated world file to the new name specified. The TIFF world file is a file containing map information. It is not part of the GeoTIFF specification, but it is in common use due to its support by the ESRI product offering.

224

IFD Implementation tiffLayerCreate Description The tiffLayerCreate function creates a new layer in a TIFF file. There is currently no limit imposed on the number of layers that can be created in a TIFF file, but the DLL does not yet support multiple IFDs in the TIFF file. The consequences of this are that layers with different dimensions, compressions, or pixel types are not allowed. Also, the color tables, georeferencing, and geocoding of all layers are shared (since they will all be created within the same IFD). This happens (mostly) silently, so the last modification to the file rules for all layers. A preference is provided that allows the default compression to be selected. There is also a preference that determines whether the TIFF image will be tiled or written in strips.

225

IFD Implementation tiffLayerDestroy Description The tiffLayerDestroy function always fails. It is provided so that the tiffLayerCreate function will be recognized and used by the class owner. It may be implemented in the future if there seems to be an overwhelming need to destroy layers in a TIFF file.

226

IFD Implementation tiffLayerOpen Description The tiffLayerOpen function sets all return values from information in the Etif_Handle portion of the TiffHandle. A TiffLayerHandle is allocated, initialized and returned. The TiffLayerHandle consists simply of the TiffHandle and the layer number that corresponds to that layer name passed as an argument to the function. A preference is provided that allows all TIFF files to be treated as read-only on open no matter what the permissions on the file actually are. This is provided so that the user can avoid inadvertently changing the image (which would cause it to be re-written) for in so doing, certain tags that are not of concern to this DLL may lost in the modification.

227

IFD Implementation tiffLayerClose Description The tiffLayerClose function simply frees the passed in TiffLayerHandle.

228

IFD Implementation tiffLayerLayerTypeRead Description The tiffLayerLayerTypeRead function returns the perceived type of the TIFF layer. Any sample (layer) within a TIFF image with a valid color table is treated as "thematic". All others are treated as "athematic".

229

IFD Implementation tiffLayerRasterRead Description The tiffLayerRasterRead function reads the specified block of raster data from either the temporary file used to hold raster edits or directly from the TIFF file via the etif_RasterRead function. LZW compressed data will not be read if the proper license is not available. A warning message is shown once per opened TIFF file.

230

IFD Implementation tiffLayerRasterWrite Description The tiffLayerRasterWrite function writes the specified block of raster data to the temporary file used to hold raster edits. The first raster modification to the file causes the temporary file to be created. During creation, any existing raster data will be copied from the TIFF file to the temporary file so that it will be properly restored, if not modified, when the file is closed. LZW compressed data will not be written if the proper license is not available. A warning message is shown once per opened TIFF file.

231

IFD Implementation tiffLayerScalarStatisticsRead Description The tiffLayerScalarStatisticsRead function returns the dMinSampleValue and dMaxSampleValue for the layer indicated in the passed TiffLayerHandle. These values are returned as the minimum and maximum values. See the tiffLayerScalarStatisticsWrite function for further information.

232

IFD Implementation tiffLayerScalarStatisticsWrite Description The tiffLayerScalarStatisticsWrite function stores the minimum and maximum values passed for the layer indicated in the passed TiffLayerHandle. When the file is closed, these values are written to the file. Although the interface to the public domain library function that performs the writing of the minimum and maximum allows for these values to be specified on a per sample basis, it does not tolerate differences between samples for these values. An attempt has been made to read and write the statistics correctly, i.e., to record the correct minimum and maximum for each sample in the TIFF file. However, even if the public domain library functions that normally perform these operations are bypassed, the public domain library function that opens the file will fail with an error if the minimum or maximum values in the file differ on a per sample basis. Until this can be corrected, the minimum and maximum written to the file will be the global minimum and maximum for all samples and the minimum and maximum read from the file will be identical for all samples.

233

IFD Implementation tiffLayerMapInfoRead Description The tiffLayerMapInfoRead returns map information in the appropriate form if it is present and in the form of a MapInfo model. The map information may come from one of three places. If there is GeoTIFF tags in the file, the map information will come from these tags. Otherwise, if there is a TIFF world file present and the user has specified through preferences that the TIFF world file is to be consulted for map information, the information comes from the TIFF world file. Finally, if neither condition above applies, pseudo map information based on the TIFF image’s ORIENTATION tag will be returned if the user’s preferences dictate.

234

IFD Implementation tiffLayerMapInfoWrite Description The tiffLayerMapInfoWrite function stores the passed in map information for later update to the file. Map information is always written in a GeoTIFF compliant manner into the TIFF file. Optionally, the user may also indicate through preferences that a TIFF world file is also to be maintained with the map information. Although this function is called for a specific layer, it will affect the every layer of the TIFF image.

235

IFD Implementation tiffLayerMapToPixelTransformRead Description The tiffLayerMapToPixelTransformRead function returns a map to pixel transformation in the appropriate form if one was found during the egtf_GeoTIFFParamsGeoreferencingGet function call. This function is necessary because the GeoTIFF specification supports map information that includes rotation (which cannot be represented as a MapInfo model). There is currently no way through this DLL to update a TIFF file with map information that is represented as an affine transformation with a rotational component. The image must be saved as another format (e.g., IMG) and then exported to TIFF with the TIFF exporter.

236

IFD Implementation tiffLayerMapProjectionRead Description The tiffLayerMapProjectionRead function returns a map projection in the correct form if GeoTIFF geocoding is present and able to be translated.

237

IFD Implementation tiffLayerMapProjectionWrite Description The tiffLayerMapProjectionWrite function saves a map projection for later inclusion in the TIFF file. If a GeoTIFF geocoding translation is possible, this translation will be placed in the file when it is closed. Although this function is called for a specific layer, it will affect the every layer of the TIFF image.

238

IFD Implementation tiffLayerColorModTimeGet Description The tiffLayerColorModTimeGet function returns (time_t)0 if the colorTableSize of the Etif_Handle of the TiffHandle of the TiffLayerHandle is greater than zero and the specific color column has not been deleted since the layer was opened. Otherwise, (time_t)-1 is returned.

239

IFD Implementation tiffLayerColorRead Description The tiffLayerColorRead function returns the specified data for the specified color if a color table is present. The presence of a color table is determined by the presence of the TIFFTAG_COLORMAP tag and corresponding red, green, and blue color tables. The color values are integers that have the same range as an unsigned short value. These are scaled appropriately for return across the interface.

240

IFD Implementation tiffLayerColorWrite Description The tiffLayerColorWrite function stores the specified data for the specified color so that the color map of the image may be updated when the file is closed. The DLL does not complain if not all color columns ("Red", "Green", and "Blue") are not updated with color information before the file is closed. This may result in the unmodified colors having invalid data in the file.

241

IFD Implementation tiffLayerColorDestroy Description The tiffLayerColorDestroy function marks the specified color as destroyed. If all color columns are destroyed, a color map will not be written and the photometric interpretation of the image will be modified to something other than ETIF_PALETTE_COLOR when the file is closed.

242

DLL Implementation uai DLL Class Membership RasterFormats Description The uai DLL implementation is intended to allow any image served by the RasterFormats DLL Class to be accessed in a manner that allows update regardless of the particular access characteristics of the referenced image with respect to the user accessing it or the world in general. This characteristic is desirable, for instance, when the user wishes to georeference an image on a CDROM or read-only NFS file system but does not wish to copy the entire image to a file system location that allows this to be done. The uai format is a simple ASCII file format that has the following syntax: IMAGINE Unrestricted Access Image:

The is an externalized file name, as defined by the efnp package, representing the referenced image that is desired to be accessed for update. Access of the .uai file through the uai DLL gives the user the impression that full update capabilities are possible on the referenced file. In reality, all of the original image data will be read from the referenced file and any updates will be read from/written to the associated .aux file that will automatically be created and accessed by the class owner (eimg). Interface Function Support The uai DLL does not have any image creation capability that is accessible through the interface functions defined in the RasterFormats DLL Class. The DLL will provide the uaiUAIFileCreate interface function, however, that will be accessible if the uai DLL is linked to directly. The uai DLL supplies implementations for all interface functions defined by the RasterFormats DLL class that are for reading data. It supplies none of the interface functions defined by the RasterFormats DLL class that are for writing data. In most cases, the interface functions are implemented by accessing the referenced file through the eimg interface. This will necessitate ensuring that the eimg functions that are utilized in this manner are recursively re-entrant. In cases where optional non-modification interface functions are omitted from the implementation specification, it is thought that the default behavior of the system is correct for this DLL. There are three interface functions that are known exceptions to this rule:

243

InstanceCompressionTypesGet, InstanceRasterDataOrderTypesGet, FileRasterDataOrderGet. Since these functions are not implemented, the eimg_LayerCompressionTypeQuery function will always return "None" instead of reflecting the actual compression type of the underlying referenced image and the underlying image will always appear to be "BSQ", when, in fact, it may have a different raster data order.

244

IFD Implementation uaiUAIFileCreate Syntax int uaiUAIFileCreate( char *fileName, char *referenedFileName )

/* Input */ /* Input */

Description The uaiUAIFileCreate function creates a UAI file named fileName that references the file referencedFileName. fileName and referencedFileName should both be internalized file names as defined by the efnp package. Return Value This function returns 0 for success and -1 for failure. It is considered an error if fileName already exists.

245

IFD Implementation uaiInstanceTitleListGet Description The uaiInstanceTitleListGet function returns a single title: "Unrestricted Access Image".

246

IFD Implementation uaiInstanceDescriptionGet Description The uaiInstanceDescriptionGet function returns the following short description of the uai format: @(#)$RCSfile$ $Revision$ $Date$ The uai instance of the RasterFormats DLL Class provides unrestricted access to raster imagery in any format supported by another RasterFormats DLL. This allows the user to 'update' a referenced file on a CDROM or in a read-only network directory via a .uai proxy file.

247

IFD Implementation uaiInstanceTemplateListGet Description The uaiInstanceTemplateListGet function returns a single template: "*.uai".

248

IFD Implementation uaiInstanceExtListGet Description The uaiInstanceExtListGet function returns a single extension: ".uai".

249

IFD Implementation uaiInstanceShortNameListGet Description The uaiInstanceShortNameListGet function returns a single name: "uai".

250

IFD Implementation uaiFileTitleIdentifyAndOpen Description The uaiFileTitleIdentifyAndOpen function has the job of ensuring that the passed in file is of the correct format. It must also allocate space for a file handle and open the file. The verification step is straightforward. The named file must exist and must begin with the contents "IMAGINE Unrestricted Access Image:". The remaining data before the first newline character is considered the file name. White space is not trimmed. All data beyond the first newline is ignored. If this function is called with a creation mode, an error will always be indicated. If this function is called for verification only, the file exists and the beginning contents of the file are correct, 0 will be indicated for the title index (the only available title index for this DLL). If the call is made in such a way that the file is actually to be opened, the function will open the named file, determine the referenced file name, close the named file, and verify that the referenced file is accessible. If the referenced file is not accessible, an error will be returned for the open. If the referenced file is accessible, the referenced file name will be returned as the open file handle. If the call is made in such a way that the file is actually to be opened, this function also makes sure that the referenced file is not self referenced and the referenced file is not another UAI file. This will prevent infinite loops if a mistake is made somewhere.

251

IFD Implementation uaiFileClose Description The uaiFileClose function frees the passed in file handle, which is simply a character string file name.

252

IFD Implementation uaiFileModTimeGet Description The uaiFileModTimeGet function performs an uaiFileTitleIdentifyAndOpen with its fileName argument, calls eimg_FileModTimeGet with the referenced file name and then performs a uaiFileClose.

253

IFD Implementation uaiFileDataModTimeGet Description The uaiFileDataModTimeGet function performs an uaiFileTitleIdentifyAndOpen with its fileName argument, calls eimg_FileNodeDataModTimeGet with the referenced file name and the dataName argument fused into a file node list, and then performs a uaiFileClose.

254

IFD Implementation uaiFileDataRead Description The uaiFileDataRead function performs an uaiFileTitleIdentifyAndOpen with its fileName argument, calls eimg_FileNodeDataRead with the referenced file name and the dataName argument fused into a file node list, and then performs a uaiFileClose. It then converts the returned design and object to MIF for return across the interface, if necessary (the named object may not have been there).

255

IFD Implementation uaiInstancePixelTypesGet Description The uaiInstancePixelTypesGet function returns the complete list of supported pixel types as defined by the RasterFormats DLL Class so that it can correctly reflect the pixel type of any referenced image.

256

IFD Implementation uaiInstanceLayerTypesGet Description The uaiInstanceLayerTypesGet function returns the complete list of supported layer types as defined by the RasterFormats DLL Class so that it can correctly reflect the layer type of any referenced image.

257

IFD Implementation uaiFileLayerNamesGet Description The uaiFileLayerNamesGet function calls eimg_LayerNamesGet with the file handle passed to it converted to a character string referenced file name. It then converts the returned Estr_StringList to a form compatible with passage across the user interface.

258

IFD Implementation uaiFileCovarianceRead Description The uaiFileCovarianceRead function calls eimg_FileCovarianceRead with the file handle passed to it converted to a character string referenced file name. It then converts the returned Esta_Covariance to a form compatible with passage across the user interface, if necessary.

259

IFD Implementation uaiFileRasterFormatsNonStandardDataNamesGet Description The uaiFileRasterFormatsNonStandardDataNamesGet function calls eimg_FileNonStandardObjectList with the file handle passed to it converted to a character string referenced file name. It then converts the returned Estr_StringList to a form compatible with passage across the user interface, if necessary. This interface function is primarily used to allow non-standard objects (such as ephemeris data nodes) to be copied

260

IFD Implementation uaiLayerOpen Description The uaiLayerOpen function calls eimg_LayerOpen by fusing the fileHandle passed to it (converted to a character string referenced file name) to the layerName passed to it into a layer name using eimg_LayerNameCreate. The only option specified will be EIMG_LAYER_OPTION_READONLY. The returned pType, width, height, bWidth and bHeight call all be obtained from structure members in the Eimg_Layer. The returned compression is always set to 0. It then casts the returned Eimg_Layer to a void * for use as the layer handle.

261

IFD Implementation uaiLayerClose Description The uaiLayerClose function calls eimg_LayerClose with the layerHandle passed to it cast to an Eimg_Layer *.

262

IFD Implementation uaiLayerLayerTypeRead Description The uaiLayerLayerTypeRead function accesses and returns the layerType structure member of the layerHandle passed to it (cast to an Eimg_Layer *).

263

IFD Implementation uaiLayerRasterRead Description The uaiLayerRasterRead function calls eimg_LayerRead with the layerHandle passed to it cast to an Eimg_Layer *. It computes the starting x and y position to read based on the passed in bRow and bCol parameters and using the blockWidth and blockHeight structure members of the Eimg_Layer (these members are used for the size as well). An Eimg_PixelRect for the read can be created as an Egda_BaseData that is derived from the *pixels parameter passed. Although this makes the uai DLL aware that an Eimg_PixelRect is an Egda_BaseData, it saves a memory copy.

264

IFD Implementation uaiLayerRasterModTimeGet Description The uaiLayerRasterModTimeGet function calls eimg_LayerGetTimeStamp with the layerHandle passed to it cast to an Eimg_Layer *. The returned value is then cast to a type appropriate for return across the interface.

265

IFD Implementation uaiLayerRasterNullValueRead Description The uaiLayerRasterNullValueRead function accesses and returns the nonInitializedValue of the layerHandle passed to it (cast to an Eimg_Layer *). This is based on the private knowledge that this structure member will be allocated and initialized when the layer is opened with eimg_LayerOpen.

266

IFD Implementation uaiLayerRRDLayerNamesGet Description The uaiLayerRRDLayerNamesGet function calls eimg_SSLayerNamesGet with the layerHandle passed to it cast to an Eimg_Layer *. It then converts the returned values to values appropriate for passage across the interface.

267

IFD Implementation uaiLayerScalarStatisticsRead Description The uaiLayerScalarStatisticsRead function calls eimg_StatisticsRead with the layerHandle passed to it cast to an Eimg_Layer *. It then converts the returned value to a value appropriate for passage across the interface.

268

IFD Implementation uaiLayerMapToPixelTransformRead Description The uaiLayerMapToPixelTransformRead function calls eimg_LayerMapInformationRead with the layerHandle passed to it cast to an Eimg_Layer *. It then converts the returned values to values appropriate for passage across the interface, if necessary.

269

IFD Implementation uaiLayerMapInfoRead Description The uaiLayerMapInfoRead function calls eimg_MapInfoRead with the layerHandle passed to it cast to an Eimg_Layer *. It then converts the returned values to values appropriate for passage across the interface, if necessary.

270

IFD Implementation uaiLayerMapProjectionRead Description The uaiLayerMapProjectionRead function calls eimg_LayerMapProjectionRead with the layerHandle passed to it cast to an Eimg_Layer *. It then converts the returned value to values appropriate for passage across the interface, if necessary.

271

IFD Implementation uaiInstanceColumnTypesGet Description The uaiInstanceColumnTypesGet function returns the complete list of supported column types as defined in the DescriptorTables DLL Class document. This is necessary to support any referenced file.

272

IFD Implementation uaiTableOpen Description The uaiTableOpen function calls eimg_TableOpen by using the dataSource passed to it (cast to a referenced file name) combined with the tableName passed to it into a file node list that can be used as the tableName parameter to eimg_TableOpen. The table is opened read-only. It then converts the returned Edsc_Table * to a void * to be used as the tableHandle. The returned numRows comes from the numRows structure member of the Edsc_Table *.

273

IFD Implementation uaiTableClose Description The uaiTableClose function calls edsc_TableClose with the tableHandle passed to it cast to an Edsc_Table *.

274

IFD Implementation uaiTableColumnNamesGet Description The uaiTableColumnNamesGet function calls edsc_TableListColumns with the tableHandle passed to it cast to an Edsc_Table *. It then converts the returned Estr_StringList * to values appropriate for transfer across the interface.

275

IFD Implementation uaiColumnOpen Description The uaiColumnOpen function calls edsc_ColumnOpen with the tableHandle passed to it cast to an Edsc_Table *. The returned dataType and maxStringLength are obtained from the returned Edsc_Column *. The returned Edsc_Column * is cast to a void * to be returned as the columnHandle.

276

IFD Implementation uaiColumnClose Description The uaiColumnClose function calls edsc_ColumnClose with the columnHandle passed to it cast to an Edsc_Column *.

277

IFD Implementation uaiColumnModTimeGet Description The uaiColumnModTimeGet function calls edsc_ColumnGetTimeStamp with the columnHandle passed to it cast to an Edsc_Column *. The returned value is cast to time_t * for return across the interface.

278

IFD Implementation uaiColumnDataRead Description The uaiColumnDataRead function calls edsc_ColumnRead with the columnHandle passed to it cast to an Edsc_Column *. An Egda_BaseData for the read can be created as an Egda_BaseData that is derived from the data parameter passed.

279

DLL Class DescriptorTables Description The DescriptorTables DLL Class is a virtual class that defines a common interface to tabular data residing in a persistent data source. The class definition does not specify how the connection to the data source is obtained. This detail must be described by any DLL Class that inherits this interface. The DescriptorTables IFDs are concerned with reading from and writing to tables of information. A table is a two-dimensional array of data. As with most tabular representations, the two dimensions of the array are referred to as rows and columns. All elements of a single column of the table must have the same data type but different columns of the table may represent different data types. Access to the data in tables favors column access over row access by virtue of the defined IFDs. Tables and columns are identified by name. The naming convention for tables and columns is not specified by the DLL Class. The DescriptorTables DLL Class is owned by the edsc API. Instances in Current Version Among the DLL Classes defined in the current version of IMAGINE, RasterFormats is the only DLL Class that inherits from the DescriptorTables DLL Class. Interface Function Definitions The interface functions of the DescriptorTables DLL Class fall into three groups: Instance interface functions, Table interface functions and Column interface functions. Instance Interface Functions The Instance interface functions in this DLL class describe general capabilities of the data source(s) handled by an individual DLL instance. The way the Instance interface functions are defined, the capabilities must be uniform across all data sources supported by an instance. Table Interface Functions The Table Interface functions are used to obtain a table handle from the data source and to perform operations on tables, such as creation, destruction, column name querying and row count examination and modification. Column Interface Functions

280

The Column Interface functions are used to obtain a column handle and to perform operations on columns, such as creation, destruction and data access. In addition to these groupings of interface functions, five levels of support provided by a DLL instance are apprehended by the class owner based on which of the optional IFDs are supplied by the instance. These five levels of support are described below starting with the highest level of support. Each level depends on the next lower level being properly supported (e.g., if a DLL supplies the TableCreate IFD, it will not be recognized if the TableDestroy IFD is not supplied). Table Creation If the instance supplies the TableCreate interface function, the highest level of support is achieved. All operations on tables are supported in the data source(s) supported by the DLL instance. Table Update If the instance supplies the TableRowCountSet, TableColumnNamesSet and TableDestroy interface functions, table update is supported. Column Creation If the instance supplies the ColumnCreate interface function, column creation is supported. Column Update If the instance supplies the ColumnDataWrite and ColumnDestroy interface functions, column update is supported. Column Access All remaining Table and Column interface functions are required. A DLL instance providing these interface functions will enable read-only data access to tables in the data source(s) supported by it.

281

Interface Function InstanceColumnTypesGet Syntax long InstanceColumnTypesGet( unsigned long *count, char ***columnTypes )

/* Output */ /* Output */

Description The InstanceColumnTypesGet function should return in *columnTypes a list of column data types known to be supported for columns stored in tables in the data source(s) supported by the DLL. This function should place a character string list in *columnTypes which contains pointers to all type strings for column types supported by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. The count of the strings in the list should be placed in *count. The complete set of supported data types and the semantics of data transfer through the ColumnDataRead and ColumnDataWrite interface functions is described by the table below. The actual storage format of the data in the table at the data source is not specified by this DLL Class and any format that preserves data transferred in the transfer format through the ColumnDataRead and ColumnDataWrite functions is acceptable. If a column type other than the valid column types listed below is returned, any columns in tables in the data source that have that column type will be ignored. Column Type “integer”

Transfer Size (bytes) 4

Encoding An integer column type is used to hold integral values. The data in an integer column is transferred as signed 32-bit integer quantities (4 bytes) in the byte order native to the host CPU. The representable data range of this type is from -2147483646 to 2147483647.

282

Column Type

Transfer Size (bytes)

Encoding

“real”

8

A real column type is used to hold floating point values. These values are transferred in the IEEE 754 binary standard for double precision floating point numbers (8 bytes).

“complex”

16

A complex column type is used to hold complex values. These values are transferred as two floating point values, the first representing the real part of the number and the second representing the imaginary part of the number. As with the real column type, the two floating point values used to represent a complex value are transferred in the IEEE 754 binary standard for double precision floating point numbers (16 bytes total).

“string”

4

A string column type is used to hold character string values. These values are transferred via individually allocated character pointers. The maximum number of characters that needs to be preserved for each string is specified when the column is created and is retrieved when the column is opened.

Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional. If this function does not exist, or if the function returns a NULL *columnTypes list or a zero *count, all implemented Table and Column IFDs will be assumed to support only “integer” data.

283

Interface Function TableOpen Syntax long TableOpen( void char unsigned long void )

*dataSource, *tableName, *numRows, **tableHandle

/* /* /* /*

Input */ Input */ Output */ Output */

Arguments

dataSource Specifies the source of the table (usually a file handle). tableName Specifies the name of the table in dataSource. numRows Returns the number of rows in the opened table. tableHandle Returns a handle to the opened table. Description The TableOpen function should open the table named tableName in the data source indicated by dataSource. A handle to the open table that can be used as an argument to subsequent calls to Table IFDs in this DLL Class should be placed in *tableHandle. The current number of rows in the table should be placed in *numRows.

dataSource and tableName can be assumed to not be NULL. Return Value On success, zero should be returned and the output parameters should be set. If the table could not be found, *tableHandle should be set to NULL and a zero should be returned (it is not an error). On failure, -1 should be returned. Requirements This function must exist in the DLL. If the function does not exist, the DLL will be ignored.

284

Interface Function TableCreate Syntax long TableCreate( void char unsigned long void )

*dataSource, *tableName, numRows, **tableHandle

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

dataSource Specifies the data source in which the table is to be created (usually a file handle). tableName Specifies the name for the table in dataSource. numRows Specifies the initial row count for the table. tableHandle Returns a handle to the opened table. Description The TableCreate function should create a table named tableName with an initial row count of numRows in the data source indicated by dataSource. A handle to the open table that can be used as an argument to subsequent calls to Table IFDs in this DLL Class should be placed in *tableHandle.

dataSource and tableName can be assumed to not be NULL. Return Value On success, zero should be returned and the output parameters should be set. On failure, -1 should be returned. Presence of a table named tableName in dataSource should be considered an error. Requirements This function is optional.

285

Interface Function TableDestroy Syntax long TableDestroy( void char )

*dataSource, *tableName

/* Input */ /* Input */

Arguments

dataSource Specifies the source of the table (usually a file handle). tableName Specifies the name of the table in dataSource to be destroyed. Description The TableDestroy function should destroy the table named tableName in the data source indicated by dataSource.

dataSource and tableName can be assumed to not be NULL. Return Value On success, 0 should be returned. On failure, -1 should be returned. It should not be considered an error if tableName does not already exist in dataSource. Requirements This function is optional.

286

Interface Function TableClose Syntax long TableClose( void )

*tableHandle

/* Input */

Arguments

tableHandle Specifies the table to be closed. Description The TableClose function should close the table indicated by tableHandle.

tableHandle can be assumed to not be NULL. The closing of a table is an indication to the DLL that no interface function will be called with tableHandle as an argument after a call to TableClose (i.e., it is safe to free any memory associated with tableHandle). Return Value On success, 0 is returned. On failure, -1 is returned. Requirements This function must exist in the DLL. If the function does not exist, the DLL will be ignored.

287

Interface Function TableColumnNamesGet Syntax long TableColumnNamesGet( void *tableHandle, unsigned long *count, char ***columnNames )

/* Input */ /* Output */ /* Output */

Arguments

tableHandle Specifies the table for which column names are to be listed. count Returns the number of columns in tableHandle.

columnNames Returns count character strings representing the names of the columns in tableHandle. Description The TableColumnNamesGet function should return a list of column names for the table indicated by tableHandle.

tableHandle and count can be assumed be non-NULL. This function should place a character string list in *columnNames which contains pointers to all column name strings for the existing columns in tableHandle. The array should be dynamically allocated so as to be freeable by the caller. The count of strings in the list should be returned in *count. Each string in the list should also be dynamically allocated so as to be freeable by the caller. Return Value This function should return 0 upon success and -1 for failure. Requirements This function must exist in the DLL. If the function does not exist, the DLL will be ignored.

288

Interface Function TableColumnNamesSet Syntax long TableColumnNamesSet( void *tableHandle, unsigned long count, char **oldColumnNames, char **newColumnNames )

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

tableHandle Specifies the table in which column names are to be modified. count Specifies the number of strings in oldColumnNames and newColumnNames.

oldColumnNames Specifies count character strings representing the current names of the columns whose names are to be changed. newColumnNames Specifies count character strings representing the new names of the columns whose names are to be changed. Description The TableColumnNamesSet function should modify the names of the columns in tableHandle that are listed in oldColumnNames so that they can be referred to by the names listed in newColumnNames.

tableHandle, oldColumnNames, and newColumnNames can be assumed to be nonNULL. Additionally, the contents of oldColumnNames and newColumnNames can be assumed to be non-NULL. Return Value This function should return 0 upon success and -1 for failure. Requirements This function is optional.

289

Interface Function TableRowCountGet Syntax long TableRowCountGet( void *tableHandle, unsigned long *rowCount )

/* Input */ /* Input */

Arguments

tableHandle A table whose number of rows is to be queried. Description The TableRowCountGet function should set *count to reflect the current number of rows in tableHandle. Return Value This function should return 0 upon success and -1 for failure. Requirements This function is optional. If the function is not provided, the information obtained or passed during the TableOpen, TableCreate and TableRowCountSet calls will be deemed to accurately reflect the row count.

290

Interface Function TableRowCountSet Syntax long TableRowCountSet( void *tableHandle, unsigned long rowCount )

/* Input */ /* Input */

Arguments

tableHandle Specifies a table whose row count is to be modified. rowCount Specifies the new row count for tableHandle. Description The TableRowCountSet function should modify the row count in tableHandle so that it is equal to rowCount. If rowCount is greater than the current number of rows in tableHandle, the table should be extended. This definition does not specify what values should be placed in the new rows of the table. If rowCount is less than the current number of rows in tableHandle, the table should be truncated. Return Value This function should return 0 upon success and -1 for failure. Requirements This function is optional.

291

Interface Function ColumnOpen Syntax long ColumnOpen( void *tableHandle, char *columnName, unsigned long *dataType, unsigned long *maxStringLength, void **columnHandle )

/* /* /* /* /*

Input */ Input */ Output */ Output */ Output */

Arguments

tableHandle Specifies a table containing a column to be opened. columnName Specifies the name of the column to be opened. dataType Returns the data type of columnName. maxStringLength If dataType indicates the “string” type, maxStringLength returns the maximum length for any string in columnName. Otherwise, this parameter is ignored. columnHandle Returns a handle to the opened column. Description The ColumnOpen function should return from the column indicated by tableHandle and columnName the data type and maximum string length (if applicable) for the column, as well as a handle for the column that may be used for subsequent operations on the column. The data type for the column should be an integer index into the array of valid column types for this file format that is returned by the InstanceColumnTypesGet function. The value of this integer index should be placed in *dataType. If *dataType indicates a “string” column, the maximum string length should be placed in *maxStringLength. Otherwise, the value of *maxStringLength will be ignored.

tableHandle and columnName can be assumed to be non-NULL. columnName can be

292

assumed to be one of the names returned by TableColumnNamesGet for the table indicated in tableHandle. Return Value The function should return 0 upon success and -1 on failure. Requirements This function must exist in the DLL. If the function does not exist, the DLL will be ignored.

293

Interface Function ColumnCreate Syntax long ColumnCreate( void char unsigned long unsigned long void )

*tableHandle, *columnName, dataType, maxStringLength, **columnHandle

/* /* /* /* /*

Input */ Input */ Input */ Input */ Output */

Arguments

tableHandle Specifies a table in which a column is to be created. columnName Specifies the name of the column to be created. dataType Specifies the data type of columnName. maxStringLength If dataType indicates the “string” type, maxStringLength specifies the maximum length for any string in columnName. Otherwise, this parameter is ignored. columnHandle Returns a handle to the opened column. Description The ColumnCreate function should create a column in the table indicated by tableHandle. The created column should have the name columnName and should be capable of storing data of type dataType. A handle for the column that may be used for subsequent operations on the column should be returned in *columnHandle after successful completion of the function call. The data type for the column is specified as an integer index into the array of valid column types for this file format that is returned by the InstanceColumnTypesGet function. If dataType indicates a “string” column, the maximum string length for the column will be indicated by maxStringLength. Otherwise, the value of maxStringLength has no meaning.

tableHandle and columnName can be assumed to be non-NULL. columnName can be

294

assumed to not be one of the names returned by TableColumnNamesGet for the table indicated in tableHandle. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

295

Interface Function ColumnDestroy Syntax long ColumnDestroy( void *tableHandle, char *columnName )

/* Input */ /* Input */

Arguments

tableHandle Specifies a table containing a column to be destroyed. columnName Specifies the name of the column to destroy. Description The ColumnDestroy function should remove the column indicated by columnName from the table indicated by tableHandle.

tableHandle can be assumed to be non-NULL and columnName can be assumed to be one of the names returned by TableColumnNamesGet. Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

296

Interface Function ColumnClose Syntax long ColumnClose( void *columnHandle )

/* Input */

Arguments

columnHandle Specifies a column to close. Description The ColumnClose function should close the column indicated by columnHandle.

columnHandle can be assumed to not be NULL. The closing of a column is an indication to the DLL that no interface function will be called with columnHandle as an argument after a call to ColumnClose (i.e., it is safe to free any memory associated with columnHandle). Return Value The function should return 0 upon success and -1 on failure. Requirements This function must exist in the DLL. If the function does not exist, the DLL will be ignored.

297

Interface Function ColumnModTimeGet Syntax long ColumnModTimeGet( void *columnHandle, time_t *modTime )

/* Input */ /* Output */

Arguments

columnHandle Specifies a column to be queried. modTime Returns the last modification time of the column indicated by columnHandle. Description The ColumnModTimeGet function should retrieve the time of the last modification to the column indicated by columnHandle and place it in *modTime. The modification time should be encoded in the same manner as the System V interface definition (the number of seconds since 00:00:00 GMT, Jan. 1, 1970). If the time of the last modification of the column cannot be obtained, setting *modTime to (time_t)0 is acceptable but may cause annoying (though not incorrect) application behavior. (time_t is an ANSI C defined data type obtainable by including .)

columnHandle and modTime can be expected to be non-NULL. Return Value A zero should be returned on success and a -1 on failure. Requirements This function must exist in the DLL. If the function does not exist, the DLL will be ignored.

298

Interface Function ColumnDataRead Syntax long ColumnDataRead( void unsigned long unsigned long unsigned char )

*columnHandle, startRow, numRows, *data

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

columnHandle Specifies the column from which to read data. startRow Specifies the row of the table from which to begin reading data. numRows Specifies the number of rows to read. data Returns the read data. Description The ColumnDataRead function should return numRows of data beginning and including startRow from the column indicated by columnHandle.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows in the table in which the column indicated by columnHandle resides. This function can assume that columnHandle will be non-NULL.

data can be assumed to point to a memory area large enough to hold numRows X Transfer Size bytes of data, as described by the table in the InstanceColumnTypesGet function description. Be aware that for transfer of data of type “string”, each character string pointer returned in data must have been separately allocated so as to be freeable by the caller. Each string pointer must also point to a NULL terminated character string.

299

Return Value The function should return 0 upon success and -1 on failure. Requirements This function must exist in the DLL. If the function does not exist, the DLL will be ignored.

300

Interface Function ColumnDataWrite Syntax long ColumnDataWrite( void unsigned long unsigned long unsigned char )

*columnHandle, startRow, numRows, *data

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

columnHandle Specifies the column to which data is to be written. startRow Specifies the row of the table to which to begin writing data. numRows Specifies the number of rows to write. data Specifies the data to be written. Description The ColumnDataWrite function should record numRows of data beginning and including startRow in the column indicated by columnHandle.

startRow is indexed from 0. startRow + numRows can be assumed to not exceed the number of rows in the table in which the column indicated by columnHandle resides. This function can assume that columnHandle will be non-NULL.

data can be assumed to point to a memory area large enough to hold numRows X Transfer Size bytes of data, as described by the table in the InstanceColumnTypesGet function description. Be aware that for transfer of data of type “string”, each character string pointer in data will point to a NULL terminated character string. This function should not assume that the maxStringLength restriction of the ColumnCreate or ColumnOpen function has been enforced by the caller (i.e., the NULL terminated character strings may be greater than or less than maxStringLength).

301

Return Value The function should return 0 upon success and -1 on failure. Requirements This function is optional.

302

303

DLL Class GeometricModels Description Polynomial transformations and even rational function transformations are not sufficient to model the various geometries which are present in imagery. We are interested in the geometry associated with remotely sensed data so that the geometric properties of the collected data can be related to a known map system through a geometric transformation. The GeometricModels DLL Class, derived from the DLLs DLL Class, provides an interface that allows third party developers and end users to develop GeometricModels from sensors and sensor platforms that will be used in IMAGINE for coordinate transformations. More generally, any geometric transformation (not necessarily sensor based) can be supported through a DLL Instance of the GeometricModels DLL Class. The class owner of the GeometricModels DLL Class is the exfr package. This package provides a generic API that allows a programmer to create, copy, invert, compose, and transform points through a GeometricModels object, the implementation of which is unknown to the programmer. The primary data type of the exfr package, the Exfr_XForm, is an arbitrary transformation which can be used to transform an [x,y] pair to a new [x,y] pair. Its most common application is in the transformation of file coordinates to map coordinates and vice versa. The exfr package and the GeometricModels DLL Class currently only support 2D->2D transformations, but both the Class Owner and the Class Definition can be extended in the future to allow nD->mD transformations without breaking existing applications or existing DLL Instances. Examples of the use of Exfr_XForm’s in IMAGINE include support of the MapToPixelTransformation object associated with a raster data layer (sometimes referred to as the ‘Geometric Calibration’) as well as the simple affine transformations supported by the IMAGINE Viewer (rotation, zoom in, zoom out, pan, reflect, etc.). The composition of such transformation objects establishes a new object that governs the transformation of raster, vector and annotation objects read into a map frame in the IMAGINE Viewer both in the normal Viewer context and in the context of a map frame within a Map Composer. The GeometricModels DLL Class has two companion classes, the GeomodelInterfaces DLL Class and the ResampleMethods DLL Class. There is an established convention of giving related DLL Instances in these companion classes the same instance name. The GeomodelInterfaces DLL Class supports the creation of a geometric model through the Geometric Correction Tool in IMAGINE 8.3. Notably absent from the standard interface function definitions of the GeometricModels DLL Class are interface functions to create a GeometricModels object based on specific parameters. The reason for this

304

is that each model has a unique set of parameters associated with it, so it is difficult to establish a common interface to model creation and editing. The exceptions to this are certain models supported through the exfr package prior to the introduction of the GeometricModels DLL Class (affine, polynomial, and projection pair). To support these previously existing exfr functions, there are extensions to the standard set of interface function definitions for these three DLL Instances. These extensions must be implemented by any developer wishing to replace these DLL Instances with a different implementation. Failure to do so will cause IMAGINE to function improperly. The other companion class to the GeometricModels DLL Class, the ResampleMethods DLL Class, supports methods for resampling raster data. Through this class, a developer can introduce one or more ResampleMethods that are aware of a particular GeometricModels object. Knowledge of a GeometricModels object can be used by a ResampleMethods DLL Instance to optimize the resampling of raster data. The available DLLs in the GeometricModels DLL Class will be identified by the class owner via the ERDAS_GEOMETRIC_MODELS_PATH environment variable. The default value for this environment variable when running IMAGINE is: ERDAS_GEOMETRIC_MODELS_PATH=”./GeometricModels:${PERSONAL}/ GeometricModels:$IMAGINE_HOME/usr/lib/${ARCHM}/GeometricModels”

The GeometricModels DLL Class Special Instances Normally, transformations that are objects from the GeometricModels DLL Class will come into being through a creation interface provided in the GeomodelInterfaces DLL Class. The exfr package does have the need to support non-graphic GeometricModels creation for certain types of transformations, however. These transformations will be supported by DLLs distributed by ERDAS. These DLLs may be replaced, but if they are, the DLL writer must provide additional interface functions or IMAGINE applications will not continue to behave in the same manner. Specifically, DLL Instances supporting the titles “Affine”, “Polynomial” and “Projection Pair” must supply the additional interface functions. Instances in Current Version The following instances of GeometricModels DLLs are distributed with the current version of IMAGINE: DLL Instance

GeometricModel

affine.dll

Affine Model

camera.dll

Camera Model

305

DLL Instance

GeometricModel

landsat.dll

Landsat Model

orthosar.dll

Radarsat Model ERS Model

polynomial.dll

Nth Order Polynomial Model

projpair.dll

Reprojection Model

rubbers.dll

Rubber Sheeting Model

spot.dll

SPOT Model

Interface Function Definitions Each instance of the GeometricModels DLL Class will support the InstanceTitleListGet interface function, support of which is inherited from the DLLs DLL Class. This interface function should return a list of the XForm titles supported by the DLL Instance. The remaining interface functions are defined below. Prototypes for all interface functions are available to the users of the IMAGINE Toolkit via the header file /usr/ include/exfr_GeometricModels.h If you create a DLL Instance that supports more than one type of GeometricModels object, all representations of the object (i.e., MIF, ASCII and internal void *) must contain an indication of what type of GeometricModels object it is because this information, although known by the Class Owner, is not explicitly passed to the interface functions as a formal argument.

306

Interface Function XFormConvertFromMIF Syntax long XFormConvertFromMIF( unsigned char char char void )

*MIFXform, *MIFDictionary, *MIFName, **xform

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

MIFXform MIF xform MIFDictionary ASCII MIF Dictionary describing MIF xform MIFName Name of design in MIFDictionary for xform xform Internal form of xform Description The XFormConvertFromMIF function should convert the MIF object, MIFXform, into the appropriate internal representation by using the MIFDictionary and MIFName (see XFormConvertToMIF). The created object should be placed in *xform.

xform can be assumed to be non-NULL. MIFXform can be assumed to have been encoded using this DLL Instance’s XFormConvertToMIF function. Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional. However, the XFormConvertFromMIF and XFormConvertToMIF functions must both be available in order for either one of them to be used. Also, if neither the XFormSprintf/XFormSscanf pair nor the XFormConvertToMIF/XFormConvertFromMIF pair are provided, the XForm’s controlled by the DLL Instance obviously cannot be saved which severely limits the utility

307

of the DLL Instance. The construction of a DLL Instance in this manner is strongly discouraged.

308

Interface Function XFormConvertToMIF Syntax long XFormConvertToMIF( void unsigned char char char )

*xform, **MIFXform, **MIFDictionary, **MIFName

/* /* /* /*

Input Output Output Output

*/ */ */ */

Arguments

xform Internal form of xform

MIFXform MIF xform MIFDictionary ASCII MIF Dictionary describing MIF xform MIFName Name of design in MIFDictionary for xform Description The XFormConvertToMIF function should convert the transform parameter, xform, to a machine independent format. A pointer to a MIF object representing the XForm should be placed in MIFXform. A pointer to an ASCII encoded MIF dictionary (see the ERDAS Field Guide) representing the MIF design(s) defining the MIFXform should be placed in MIFDictionary. The name of the design in the MIF dictionary representing the MIFXform should be placed in MIFName.

xform, MIFXform, MIFDictionary and MIFName can all be assumed to be non-NULL. Return Value This function should return the size of MIFXform on success and -1 on failure. Requirements This function is optional. However, the XFormConvertFromMIF and XFormConvertToMIF functions must both be available in order for either one of them to be used. Also, if neither the XFormSprintf/XFormSscanf pair nor the

309

XFormConvertToMIF/XFormConvertFromMIF pair are provided, the XForm’s controlled by the DLL Instance obviously cannot be saved which severely limits the utility of the DLL Instance. The construction of a DLL Instance in this manner is strongly discouraged.

310

Interface Function XFormSscanf Syntax void * XFormSscanf( char )

*xformString

/* Input */

Arguments

xformString Transform to read Description The XFormSscanf function should parse the contents of the ASCII character string pointed to by xformString and create and return the resulting XForm object.

xformString can be assumed to have been output by the DLL Instance’s XFormSprintf function. Return Value The function should return a valid XForm upon success and NULL for failure. Requirements This function is optional. However, the XFormSprintf and XFormSscanf functions must both be available in order for either one of them to be used. Also, if neither the XFormSprintf/XFormSscanf pair nor the XFormConvertToMIF/ XFormConvertFromMIF pair are provided, the XForm’s controlled by the DLL Instance obviously cannot be saved which severely limits the utility of the DLL Instance. The construction of a DLL Instance in this manner is strongly discouraged. If no XFormSprintf/XFormSscanf pair is provided by a DLL, the GeometricModels objects supported by the DLL cannot be represented in an .atx file associated with a non.img file of raster imagery (see the RasterFormats DLL Class documentation).

311

Interface Function XFormSprintf Syntax char * XFormSprintf( void )

*xform

/* Input */

Arguments

xform Transform to print Description The XFormSprintf function should print the contents of the object pointed to by xform to an ASCII character string so that it is completely recoverable through the XFormSscanf function.

xform can be assumed to be non-NULL. Return Value The function should return a non-NULL character string upon success and NULL if an error occurs. Requirements This function is optional. However, the XFormSprintf and XFormSscanf functions must both be available in order for either one of them to be used. Also, if neither the XFormSprintf/XFormSscanf pair nor the XFormConvertToMIF/ XFormConvertFromMIF pair are provided, the XForm’s controlled by the DLL Instance obviously cannot be saved which severely limits the utility of the DLL Instance. The construction of a DLL Instance in this manner is strongly discouraged. If no XFormSprintf/XFormSscanf pair is provided by a DLL, the GeometricModels objects supported by the DLL cannot be represented in an .atx file associated with a non.img file of raster imagery (see the RasterFormats DLL Class documentation).

312

Interface Function XFormDestroy Syntax long XFormDestroy( void )

*xform

/* Input */

Arguments

xform xform to be destroyed Description The XFormDestroy function should free all memory associated with the geometric transformation, xform.

xform can be assumed to have been created through either the XFormCopy, XFormInvert, XFormConvertFromMIF, or XFormSscanf function from this DLL Class or through the ModelXFormGet function of the GeomodelInterfaces DLL Class or through one of the instance-specific extension functions of this DLL Class, if this DLL Instance requires extension functions. Return Value The return value of this function is ignored by the Class Owner. The function should always return 0. Requirements If this function does not exist, the DLL will be ignored by the Class Owner.

313

Interface Function XFormIsUsable Syntax long XFormIsUsable( void )

*xform

/* Input */

Arguments

xform xform to be check for usability Description The XFormIsUsable function is used to determine if xform is usable in its current form. A ‘usable’ transformation is one that is appropriate as an argument to any other GeometricModels interface function and that any such formed function call will not result in any error(s) that would otherwise have been avoidable by editing the contents of the transformation. As an example, if the internal form of xform includes file references and those referenced files need to be opened and accessed during some GeometricModels interface function call(s) that supplies the xform as an argument, an error may be generated if those files cannot be opened at the time the function call(s) is(are) made. In this example, the errors would not have been generated had the internal file references been resolvable. Thus, this piece of information can be used as a criterion for usability of this transformation. On the other hand, availability of system resources (e.g., memory) would not be used as a criterion for usability. In general, if a potential problem with a transformation can be corrected by supplying an XFormEdit function to some GeomodelInterfaces DLL Instance and having the user make the required edits to some attribute(s) of the transformation, the attribute(s) and its(their) method of utilization should be used as criteria for usability.

xform can be assumed to have been created through either the XFormCopy, XFormInvert, XFormConvertFromMIF, or XFormSscanf function from this DLL Class or through the ModelXFormGet function of the GeomodelInterfaces DLL Class or through one of the instance-specific extension functions of this DLL Class, if this DLL Instance requires extension functions.

314

Return Value This function should return 1 if xform is usable and 0 if it is not. Requirements This function is optional. If it does not exist, any transformation associated with the DLL Instance will be assumed to always be usable. Supplying an implementation of this function does not alleviate the DLL Instance from the responsibility of detecting unusability and returning errors during calls to interface functions that utilize transformation attributes in a manner defined as a criterion for usability.

315

Interface Function XFormIsInverse Syntax long XFormIsInverse( void void )

*xform1, *xform2

/* Input */ /* Input */

Arguments

xform1 First transform xform2 Second transform Description The XFormIsInverse function should compare the transformation objects xform1 and xform2 and determine if they are mutual inverses; i.e., the composition of xform1 and xform2 is the identity transformation.

xform1 and xform2 can be assumed to be non-NULL. Return Value This function should return 1 if the two objects are mutual inverses or 0 if they are not. Requirements This function is optional. If it does not exist, any two objects associated with the DLL Instance will be assumed not to be mutual inverses.

316

Interface Function XFormInvert Syntax long XFormInvert( void )

*xform

/* Input */

Arguments

xform Transform to invert Description The XFormInvert function should replace the contents of xform with contents that represent the inverse transformation of xform. The inversion should always be performed in-place.

xform can be assumed to be non-NULL. Return Value This function should return 0 on success and -1 on failure. Requirements If this function does not exist, the DLL will be ignored by the Class Owner.

317

Interface Function XFormCopy Syntax void * XFormCopy( void )

*xform

/* Input */

Arguments

xform Transform to copy Description The XFormCopy function should allocate and return a copy of xform.

xform can be assumed to be non-NULL. Return Value This function should return a pointer to a copy of xform on success and NULL on failure. Requirements If this function does not exist, the DLL will be ignored by the Class Owner.

318

Interface Function XFormIsSame Syntax long XFormIsSame( void void )

*xform1, *xform2

/* Input */ /* Input */

Arguments

xform1 First transform xform2 Second transform Description The XFormIsSame function should compare the transforms xform1 and xform2 and determine if they are the same.

xform1 and xform2 can be assumed to be non-NULL. Return Value This function should return 1 if the two objects are the same or 0 if they differ. Requirements This function is optional. If it does not exist, any two objects associated with the DLL Instance will be assumed to be different.

319

Interface Function XFormTransform Syntax long XFormTransform( void long double double )

*xform, count, *srcPts, *dstPts

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

xform Coordinate transform

count Number of points

srcPts Source point array

dstPts Destination pnt array Description The XFormTransform function should transform the array of count points given in srcPts and place the result in dstPts. The interpretation of the srcPts and dstPts array will depend on the domain and range of the transformation (in IMAGINE 8.3 this is always 2D->2D).

srcPts is an array of domain-dimensional vectors, [u1, u2, ..., ucount] representing the points to be transformed. Each vector is represented by domain double precision floating point numbers. dstPts is an array of range-dimensional vectors, [v1, v2, ..., vcount] representing the transformation of the srcPts coordinates. Each vector is represented by range double precision floating point numbers. For instance, if both the domain and range of xform are 2, then srcPts and dstPts are arrays ordered as x0, y0, x1, y1, x2, y2, etc. count contains the total number of points in each array.

320

xform and srcPts can be assumed to be non-NULL. If dstPts is NULL, then domain and range of the transformation are equal and the result should be placed in srcPts; i.e., inplace transformation should be performed (this does not mean that dstPts will always be NULL for every xform whose domain and range are equal). Otherwise, the result should be placed in dstPts. Return Value This function should return 0 upon success and -1 on failure. Requirements If this function does not exist, the DLL will be ignored by the Class Owner.

321

Interface Function XFormTransformWindow Syntax long XFormTransformWindow( void *xform, long *pos, long *size, double *dstPts )

/* /* /* /*

Input */ Input */ Input */ Output */

Arguments

xform Coordinate transform

pos Coordinates of start position to transform

size Size of coordinate block to transform

dstPts Destination pnt array Description The XFormTransformWindow function is designed to allow GeometricModels to optimize the transformation of integral coordinate blocks. An integral coordinate block is always present in the resampling of raster data. The interpretation of pos, size and dstPts will depend on the domain and range of the transformation (in IMAGINE 8.3 this is always 2D->2D).

pos is a pointer to a domain-dimensional vector representing the integral starting coordinate to be transformed. size is a pointer to a domain-dimensional vector representing the size of the coordinate block to be transformed. dstPts is an array of range-dimensional vectors, [v1, v2, ..., vn] representing the transformation of the coordinate block. The number of double precision floating point values used to represent each vector is the same as the number of dimensions in the range of the transformation. The number of vectors to be produced is determined by finding the absolute value of the product of all of the components of the size vector. The

322

ordering of the vectors is determined by generating the coordinates to be transformed in order. The coordinates to be transformed are computed in order by starting with the pos coordinate and allowing it to vary by one in each coordinate dimension ni times, where ni represents the component of size in a given coordinate dimension, until all combinations of variations are produced. The correct ordering is produced by allowing the ‘lowest’ coordinate dimension to vary the fastest. For instance, if both the domain and range of xform are 2 and pos = [0, 0] and size = [3, 2] then dstPts should contain 6 vectors which are the transformations of [0, 0], [1, 0], [2, 0], [0, 1], [1, 1], and [2, 1], in that order.

xform and dstPts can be assumed to be non-NULL. Return Value This function should return 0 upon success and -1 on failure. Requirements This function is optional. If it does not exist, the Class Owner will calculate the coordinates in the coordinate block to be transformed and use the XFormTransform function to transform the coordinates. If a GeometricModels object is developed without a companion ResampleMethods object, it is recommended that this function be provided and any available optimizations for transforming integral coordinate blocks be implemented within it.

323

Interface Function XFormAffinePrepend Syntax long XFormAffinePrepend( double *srcAffine, void *xform )

/* Input */ /* Input */

Arguments

srcAffine Src affine coefficients xform Coordinate transform Description The XFormAffinePrepend function should prepend the affine transformation described in srcAffine to the transform represented by xform. Here ‘Prepend’ has the meaning that the srcAffine transformation would be applied AFTER the xform transformation to any source coordinates to be transformed by the XFormTransform function.

xform and srcAffine can be assumed to be non-NULL. srcAffine is a range * (range + 1) element array of doubles representing the coefficients to the first order polynomial representing the affine transformation. For example, if the range of xform is 2, the affine transformation represented by: x’ = Ax + By + C y’ = Dx + Ey + F would be passed to this function as:

srcAffine = [ A, B, C, D, E, F ] A DLL can expect this function to be called only once for a given xform. In addition, the XFormConvertToMIF, XFormSprintf, XFormInvert and XFormIsInverse functions will not be called with an xform once it has had an affine prepended. This function call is intended to allow a GeometricModels/ResampleMethods DLL Instance combination to optimize resampling by considering an affine transformation that is to be performed in addition to the transformation that is native to the DLL. Not allowing calls to the aforementioned functions relieves every DLL from converting prepended affines to a MIF or ASCII form and having to implement affine inversion and composition.

324

Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional but should be supplied if it is desired to resample raster data with the transformations supported by this DLL Instance with an optimized ResampleMethods object. Currently the eirf package has no choice but to select the default (un-optimized) resampling with Exfr_XForm’s that are composed of more than a single transformation.

325

Interface Function XFormAffineAppend Syntax long XFormAffineAppend( void *xform, double *srcAffine )

/* Input */ /* Input */

Arguments

xform Coordinate transform

srcAffine Src affine coefficients Description The XFormAffineAppend function should append the affine transformation described in srcAffine to the transform represented by xform. Here ‘Append’ has the meaning that the srcAffine transformation would be applied BEFORE the xform transformation to any source coordinates to be transformed by the XFormTransform function.

xform and srcAffine can be assumed to be non-NULL. srcAffine is a domain * (domain + 1) element array of doubles representing the coefficients to the first order polynomial representing the affine transformation. For example, if the domain of xform is 2, the affine transformation represented by: x’ = Ax + By + C y’ = Dx + Ey + F would be passed to this function as:

srcAffine = [ A, B, C, D, E, F ] A DLL can expect this function to be called only once for a given xform. In addition, the XFormConvertToMIF, XFormSprintf, XFormInvert and XFormIsInverse functions will not be called with an xform once it has had an affine appended. This function call is intended to allow a GeometricModels/ResampleMethods DLL Instance combination to optimize resampling by considering an affine transformation that is to be performed in addition to the transformation that is native to the DLL. Not allowing calls to the aforementioned functions relieves every DLL from converting appended affines to a MIF or ASCII form and having to implement affine inversion and composition.

326

Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional but should be supplied if it is desired to resample raster data with the transformations supported by this DLL Instance with an optimized ResampleMethods object. Currently the eirf package has no choice but to select the default (un-optimized) resampling with Exfr_XForm’s that are composed of more than a single transformation.

327

Interface Function XFormAffineExtract Syntax long XFormAffineExtract( void *xform, double *affine )

/* Input */ /* Output */

Arguments

xform Transform

affine Affine transformation Description The XFormAffineExtract function should return the transformation as the coefficients of a first order polynomial representing an affine transformation, if possible.

xform and affine can be assumed to be non-NULL. affine is a range * (domain + 1) element array of doubles representing the coefficients to the first order polynomial representing the affine transformation. This function will normally only be called when the domain and range of xform are equal. For example, if the domain and range of xform are both 2, then affine will be an array that can hold at least six double’s. The affine transformation represented by: x’ = Ax + By + C y’ = Dx + Ey + F would be returned by this function as:

affine = [ A, B, C, D, E, F ] Return Value This function should return 0 for success and -1 for failure. If the transformation cannot be represented exactly by a first order polynomial, then -1 should be returned. Requirements This function is optional. If it is not present, none of the transformations controlled by this DLL Instance will be treated as affine transformations. 328

DLL Implementation affine DLL Class Membership The affine Instance of the GeometricModels DLL Class controls a single type of GeometricModels object, the affine transformation. Title Affine

Purpose Affine transformations

Description An affine transformation is equivalent to a first order polynomial transformation and is used to handle all linear transformations (rotation, scaling) as well as translation. MIF Representation The affine transformation may be written to an HFA File as a component of an Exfr_XForm. The affine transformation’s MIF Representation is as an Efga_Polynomial. MIF Dictionary Defintion {1:Lorder,1:Lnumdimtransforms,1:numdimpolynomial,1:Ltermcount, 1:*exponentList,1:bpolycoefmtx,1:bpolycoefvector,}Efga_Polynomial,

MIF Design Table Type

Name

Description

LONG

order

The order of the polynomial (always 1).

LONG

numdimtransform

The number of dimensions of the transformation (always 2).

LONG

numdimpolynomial

The number of dimensions of the polynomial (always 2).

LONG

termcount

The number of terms in the polynomial.

LONG *

exponentlist

The ordered list of powers for the polynomial.

BASEDATA

polycoefmtx

The polynomial coefficients.

329

Type BASEDATA

Name polycoefvector

Description The polynomial vectors.

330

IFD Implementation affineXFormCreateUsingCoeffs Syntax void * XFormCreateUsingCoeffs( optionsPtr ) va_list optionsPtr; optionsPtr -> double double double double double double

*A, *B, *C, *D, *E, *F

Description Create an “Affine” XForm using coefficients. Return Value

331

IFD Implementation affineXFormCreateUnity Syntax void * XFormCreateUnity( optionsPtr ) va_list optionsPtr; optionsPtr ->

Description Create an “Affine” XForm that is an identity. Return Value

332

IFD Implementation affineXFormFindAffine Syntax void * XFormFindAffine( optionsPtr ) va_list optionsPtr; optionsPtr -> Efga_Polynomial Efga_Polynomial

*from, *to

Description Create an “Affine” XForm that represents a transformation from one Efga_Polynomial to another. Return Value

333

IFD Implementation affineXFormRotate Syntax void * XFormRotate( optionsPtr ) va_list optionsPtr; optionsPtr -> double

*angle

Description Create an “Affine” XForm from a rotation angle in radians. Return Value

334

IFD Implementation affineXFormTranslate Syntax void * XFormTranslate( optionsPtr ) va_list optionsPtr; optionsPtr -> double double

*dx, *dy

Description Create an “Affine” XForm using an x and y offset. Return Value

335

IFD Implementation affineXFormScaleXY Syntax void * XFormScaleXY( optionsPtr ) va_list optionsPtr; optionsPtr -> double double

*scaleX, *scaleY

Description Create an “Affine” XForm using a scale factor. Return Value

336

IFD Implementation affineXFormCreateFromAffinePoly Syntax void * XFormCreateFromAffinePoly( optionsPtr ) va_list optionsPtr; optionsPtr -> Efga_Polynomial

*poly

Description Create an “Affine” XForm using an Efga_Polynomial. Return Value

337

IFD Implementation affineXFormCreateFromMapInfo Syntax void * XFormCreateFromMapInfo( optionsPtr ) va_list optionsPtr; optionsPtr -> Eprj_MapInfo

*mapInfo

Description Create an “Affine” XForm using an Eprj_MapInfo. The pixel to map transformation represented in the Eprj_MapInfo structure is created. Return Value

338

DLL Implementation polynomial DLL Class Membership The polynomial Instance of the GeometricModels DLL Class controls a single type of GeometricModels object, the polynomial transformation. Title Polynomial

Purpose Nth order polynomial transformations

Description A polynomial transformation is capable of representing any polynomial transformation of any order. First order polynomial transformations are normally represented by an “Affine” transformation, however. MIF Representation The polynomial transformation may be written to an HFA File as a component of an Exfr_XForm. The polynomial transformation’s MIF Representation is as a GM_PolyPair. MIF Dictionary Defintion {1:*oEfga_Polynomial,forward,1:*oEfga_Polynomial,reverse,}GM_PolyPair,

MIF Design Table Type

Name

Description

Efga_Polynomial *

forward

The forward polynomial.

Efga_Polynomial *

reverse

The inverse polynomial.

339

IFD Implementation polynomialXFormCreateFromPolyPair Syntax void * XFormCreateFromPolyPair( optionsPtr ) va_list optionsPtr; optionsPtr -> Efga_Polynomial Efga_Polynomial

*forward, *reverse

Description Create a “Polynomial” XForm using a pair of Efga_Polynomial’s. Return Value

340

DLL Implementation projection DLL Class Membership The projection Instance of the GeometricModels DLL Class controls a single type of GeometricModels object. Title

Purpose

Projection Pair Description MIF Representation MIF Dictionary Defintion MIF Design Table Type

Name

Description

341

IFD Implementation projectionXFormCreateFromProjPair Syntax void * XFormCreateFromProjPair( optionsPtr ) va_list optionsPtr; optionsPtr -> Eprj_ProjectionPair

*projPair

Description Create a “Projection Pair” XForm using an Eprj_ProjectionPair. Return Value

342

DLL Class ResampleMethods Description The ResampleMethods DLL Class, derived from the DLLs DLL Class, provides an interface that allows third party developers and end users to develop customized resample methods for use in IMAGINE. The resampling of raster data is necessary whenever it is desired to relate an image to a coordinate system that does not match its own internal pixel coordinate system, such as in georeferencing an image, relating two images, or zooming, rotating or translating an image. Refer to the ERDAS Field Guide for a more in depth discussion of raster data resampling. The class owner of the ResampleMethods DLL Class is the eirf package. This package provides an API that allows a programmer to define the parameters for resampling, including the data source, the transformation to that data source, and the resample method to apply. Once the resampling parameters are defined, resampled data blocks may be retrieved through another API function. The ResampleMethods DLL Class is constructed such that it addresses two distinct motivations for introducing new resample methods: algorithmic and efficiency. The algorithmic motivation is addressed by allowing resample methods that are unique with respect to their algorithmic nature to be introduced. These resample methods are ignorant of the transformation that is taking place to necessitate the resampling. All they require is the source pixel address of the destination pixel to be resampled and they can consider any neighboring pixel values as required by their algorithm. The efficiency motivation is addressed by allowing a resample method that is aware of a certain type of transformation to be introduced. These types of resample methods inform the class owner about which types of transformations (GeometricModels) they know about. Naming conventions for these types of resample methods (defined in eirf) allow the class owner to distinguish an optimized resampling method from a general purpose resampling method when both implement the same resampling algorithm (the former can simply do it more efficiently). The available DLLs in the ResampleMethods DLL Class will be identified by the class owner via the ERDAS_RESAMPLE_METHODS_PATH environment variable. The default value for this environment variable when running IMAGINE is: ERDAS_RESAMPLE_METHODS_PATH=”./ResampleMethods:${PERSONAL}/ ResampleMethods:$IMAGINE_HOME/usr/lib/${ARCHM}/ResampleMethods”

343

Instances in Current Version The following instances of ResampleMethods DLLs are distributed with the current version of IMAGINE: DLL Instance

Resample Methods

affine.dll

Optimized Affine resampling

camera.dll

Optimized Camera resampling

default.dll

General resampling

landsat.dll

Optimized Landsat resampling

rubbers.dll

Optimized Rubber Sheeting resampling

spot.dll

Optimized SPOT resampling

Interface Function Definitions The ResampleMethods DLL Class inherits the DLLs interface, as it is derived from that DLL Class. The titles returned by the InstanceTitleListGet function required by the DLLs interface are used as the names of the resample methods provided by a particular DLL instance. The interface functions defined by this class are included below. Note that DLL instances whose motivation is algorithmic would tend to supply the InstanceKernelSizeListGet interface function and omit the ResampleBlockCheck interface function, whereas efficiency motivated DLL instances typically do the opposite. Prototypes for all interface functions are available to the users of the IMAGINE Toolkit via the header file /usr/include/eirf_ResampleMethods.h

344

Interface Function InstanceGeometricModelsInstanceListsGet Syntax long InstanceGeometricModelsInstanceListGet( unsigned long *counts, char ***lists )

/* Output */ /* Output */

Arguments

counts Returns a list of list counts describing lists.

lists Returns a list of lists, one list for each resample method, of GeometricModels titles. Description The InstanceGeometricModelsInstanceListsGet function should return a list of appropriate GeometricModels titles for each resample method title. This interface function allows a ResampleMethods DLL instance to inform the class owner that certain resample methods supplied by it are aware of the form of certain GeometricModels, the implication being that these resample methods take advantage of their knowledge of the model to optimize the resampling of data.

counts and lists can be assumed to be non-NULL. counts should be updated with a count for each of the corresponding sub-lists returned in the lists array. Both arrays are preallocated by the caller and have as many elements as the array returned by the InstanceTitleListGet function. Each sub-list should be set to an array of character pointers representing a list of titles from the GeometricModels DLL Class. Each sub-list should be dynamically allocated so as to be freeable by the caller. Each character string in each sub-list should also be individually dynamically allocated so as to be freeable by the caller. If the count for the ith resample method title, counts[i], is non-zero, the resample method will be assumed to be suitable only for single component transformations that have any GeometricModels title among lists[i][j], where j ranges from 0 to counts[i] - 1. If the count for a particular title, counts[i], is set to zero, that indicates that the resample method has a defined behavior for any arbitrary GeometricModels title as well as composite transformations.

345

Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional. If it is not available, all resample methods served by this DLL instance will be assumed to have a defined behavior for any arbitrary GeometricModels title as well as composite transformations. Note that transformation compaction (see exfr_XFormCompact) prior to resampling may result in a transformation that is different than the one originally created. For example, a first order “Polynomial” transformation will ordinarily be compacted to an “Affine” transformation. Thus if an attempt is made to develop an optimized resampling method for “Polynomial” transformations, creation of a first order “Polynomial” is not sufficient to exercise this resampling option because the first order “Polynomial” will be compacted to “Affine”, thereby making a “Polynomial” specific resampling method invalid for the resulting transformation.

346

Interface Function InstanceKernelSizeListGet Syntax long InstanceKernelSizeListGet( unsigned long )

*kernelSizeList

/* Output */

Arguments

kernelSizeList Returns a list of kernel sizes, one for each resample method. Description The InstanceKernelSizeListGet function should return the list of kernel sizes for each resample method defined by the DLL Instance.

kernelSizeList can be assumed to be non-NULL. It is to be filled in by the InstanceKernelSizeListGet function. The array will be pre-allocated by the caller and will have the same length as the number of titles returned by the InstanceTitleListGet function and will correspond one-to-one with the titles. All resample kernels are assumed to be square. The kernel size for a given resample method is used by the class owner to increase the amount of source data provided to the ResampleBlockInterpolate function beyond what would normally be required based solely on the determined source addresses. The DLL should return a kernel size of zero for any resample methods for which the ResampleBlockCheck function is to be called. Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional. If this function is not provided and there is no ResampleBlockCheck function defined for the DLL Instance, the kernel size for all of the resample methods in the DLL will be assumed to be 1. If this function is not provided and there is a ResampleBlockCheck function defined for the DLL Instance, the ResampleBlockCheck function will be used for all of the resample methods served by the DLL instance.

347

Interface Function InstanceSrcDataTypesGet Syntax long InstanceSrcDataTypesGet)( unsigned long char )

*count, ***list

/* Output */ /* Output */

Arguments

count Returns the number of data types supported.

list Returns a list of the supported data types. Description The InstanceSrcDataTypesGet function should return the source data types handled by the particular resample methods served by this DLL Instance. This implies that handling of specific source data types may only vary on a DLL Instance basis and not on a resample type basis.

count and list can be assumed to be non-NULL. *count should be set to indicate the size of the returned *list. *list should contain character strings representing data types as defined in the InstancePixelTypesGet interface function of the RasterFormats DLL Class definition. This function should place a character string list in *list which contains pointers to all pixel type strings for the source data that may be passed to the ResampleBlockInterpolate function supplied by this DLL. The string list should be dynamically allocated so as to be freeable by the caller. The individual strings in the string list should also be freeable by the caller. Return Value This function should return 0 for success and -1 for failure. Requirements This function is optional. If this function is not provided, the resample methods defined in this DLL Instance will be assumed to only accept source data of type “u8”.

348

Interface Function ResampleDataCreate Syntax long ResampleDataCreate( unsigned long unsigned long char void char void

resampleType, srcDataType, *srcNames, *xForm, *xFormTitle, **resampleData

/* Input */ /* Input */ /* Input */ /* Input */ /* Input */ /* Output */

Arguments

resampleType Specifies the resample method desired. srcDataType Specifies the source data type to be used. srcNames Specifies the source image layer names, if applicable. xForm Specifies the transformation to be used.

resampleData Returns the data to be used for resampling. Description The ResampleDataCreate function should create a pointer to resample function specific data that may be passed to the ResampleBlockCheck and ResampleBlockInterpolate functions to control the resampling of data. This pointer should be placed in *resampleData. This function is called one time for any given transformation of data.

resampleType can be assumed to represent a valid index into the array of resample types returned by the InstanceTitleListGet function. srcDataType can be assumed to represent a valid index into the array of supported source data types returned by the InstanceSrcDataTypesGet function. If the transformation upon which the resampling will be based defines a direct transformation of image pixels stored in one or more layers of imagery, the names of the imagery layers will be passed via a file node list (see the efnp package) in srcNames. Otherwise, srcNames will be NULL.

349

The transformation, xForm, being applied may be examined by the resampling method if it is familiar with the internal representation of transformations from the GeometricModels DLL Instance that supports xFormTitle. Otherwise, the information should be ignored. Return Value This function should return 0 for success and -1 for failure. Requirements This function is required. At the very least, the resampleType and srcDataType need to be recorded for subsequent calls to the ResampleBlockInterpolate function. If this function does not exist, the DLL Instance will be ignored.

350

Interface Function ResampleDataDestroy Syntax long ResampleDataDestroy( void *resampleData )

/* Input */

Arguments

resampleData Specifies the resample data to be destroyed. Description The ResampleDataDestroy function frees the memory associated with the resample data, resampleData, which was created using the ResampleDataCreate function.

resampleData can be assumed to be non-NULL. Return Value This function should return zero upon success and -1 for failure. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

351

Interface Function ResampleBlockCheck Syntax long ResampleBlockCheck( long long void long long )

*dstPos, *dstSize, *resampleData, *srcPos, *srcSize

/* Input */ /* Input */ /* Input */ /* Output */ /* Output */

Arguments

dstPos Specifies the position of the destination sub-image being considered. dstSize Specifies the size of the destination sub-image being considered. resampleData Specifies the data controlling the resampling. srcPos Returns the position (relative to the source image origin) of the source sub-image required to produce the destination sub-image. srcSize Returns the size of the source sub-image required to produce the destination subimage. Description The ResampleBlockCheck function should compute the position (srcPos) and size (srcSize) of the sub-image of an input image required to fill a portion of the resampled image at dstPos of size dstSize.

dstPos, dstSize, srcPos, and srcSize can all be assumed to be non-NULL. Each of these pointers can be treated as an array whose length is equal to the number of dimensions of the data to be resampled (currently always 2). Thus, for example, if 2-dimensional raster data is to be resampled, dstPos will be specified as [ columnOffset, rowOffset ] and dstSize will be specified as [ widthInPixels, heightInPixels ]. srcPos and srcSize are to be returned in a similar manner. resampleData represents the data pointer returned by the

352

ResampleDataCreate function. This function, if available, will be called immediately before the ResampleBlockInterpolate function is called. (It may be called multiple times if the required input block is deemed too large by the class owner). Return Value The function should return 0 for success and -1 for failure. Requirements This function is optional. Supplying this function implies that the transformation applied to the data necessitating the resampling is understood by the resample functions. This function obviates the need for a InstanceKernelSizeListGet function if all titles supported by the DLL can use the ResampleBlockCheck function. If this function is not provided, the XFormTransform function of the GeometricModels DLL (or DLLs, in the case of a composite transformation) that supplies the transformation will be used to compute the input addresses of every pixel in the output block. Then the srcPos and srcSize parameters will be computed by finding the minimum and maximum of every coordinate direction in the returned input addresses and adjusting them based on the kernel size as determined by the InstanceKernelSizeListGet function.

353

Interface Function ResampleBlockInterpolate Syntax long ResampleBlockInterpolate( double long unsigned char long long long long unsigned char long long long void )

*srcAddrs, *srcPos, *srcBuffer, srcRowPitch, srcLayerPitch, *dstPos, *dstSize, *dstBuffer, dstRowPitch, dstLayerPitch, layerCount, *resampleData

/* Input */ /* Input */ /* Input */ /* Input */ /* Input */ /* Input */ /* Input */ /* In/Out */ /* Input */ /* Input */ /* Input */ /* Input */

Arguments

srcAddrs Specifies the location in the source image of the corresponding destination pixel for all pixels in the destination sub-image. srcPos Specifies the position (relative to the source image origin) of the source sub-image required to produce the destination sub-image. srcBuffer Specifies the source sub-image. srcRowPitch Specifies the number of unsigned char’s between consecutive rows of the source sub-image in srcBuffer. srcLayerPitch Specifies the number of unsigned char’s between consecutive layers of the source sub-image in srcBuffer. dstPos Specifies the position (relative to the destination image origin) of the destination sub-image to be produced. dstSize 354

Specifies the size of the destination sub-image to be produced.

dstBuffer Specifies a data buffer into which the destination sub-image is to be produced. dstRowPitch Specifies the number of unsigned char’s between consecutive rows of the destination sub-image in dstBuffer. dstLayerPitch Specifies the number of unsigned char’s between consecutive layers of the destination sub-image in dstBuffer. layerCount Specifies the number of image layers to resample. resampleData Specifies the data controlling the resampling. Description The ResampleBlockInterpolate function should resample the data block defined by the input parameters.

dstBuffer points to the output buffer to be filled and srcBuffer points to the data values that need to be resampled to fill dstBuffer. srcPos, dstPos, and dstSize are in the form described by the ResampleBlockCheck function. srcPos represents the offset into the source image represented by srcBuffer. srcAddrs is an array of points in the source image that correspond to the pixels in dstBuffer, i.e., the locations in the source image to be resampled (the addresses should be adjusted by srcPos in order to interpret them relative to srcBuffer). The locations are specified as a continuous array of coordinate values, with each coordinate containing as many values as there are dimensions in the data to be resampled (currently always 2). Thus, for 2-dimensional data, the srcAddrs array is specified as [ s0,0x, s0,0y, s1,0x, s1,0y, ..., sw-1,0x, sw-1,0y, s0,1x, s0,1y, ..., sw-1,h-1x, sw-1,h1y ] where [ si,,jx, si,,jy ] represents the location (in real pixel coordinates) in the source image of pixel i, j of the destination buffer. dstPos represents the origin of dstBuffer in the destination image and dstSize represents the size of dstBuffer. If the DLL Instance defines a ResampleBlockCheck function, the srcPos, dstPos, and dstSize will be the exact same values as those involved in the immediately preceding ResampleBlockCheck call and the srcAddrs pointer will be NULL. srcRowPitch and dstRowPitch represent the number of unsigned char’s between each row of pixels in srcBuffer and dstBuffer respectively. Likewise, srcLayerPitch and dstLayerPitch represent the number of unsigned char’s between each layer of pixels in srcBuffer and dstBuffer respectively. layerCount represents the number of layers to be resampled. 355

resampleData represents the data pointer returned by the ResampleDataCreate function. The data type of the source data will be the same as the data type that was passed to the ResampleDataCreate function call that created resampleData. The destination data should always be produced in the same data type as the source data. Return Value This function should return 0 for success and -1 for failure. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

356

DLL Class GeomodelInterfaces Description The GeomodelInterfaces DLL Class, derived from the DLLs DLL Class, provides an interface that allows third party developers and end users to develop customized GeometricModels creation interfaces for use in IMAGINE. The class owner of the GeomodelInterfaces DLL Class is the emod package. This package provides an interface to the DLL Class and is used primarily in the Geometric Correction Tool in IMAGINE. The GeomodelInterfaces DLL Class is a companion class to the GeometricModels DLL Class. The GeomodelInterfaces DLL Class is used to give a user of the Geometric Correction Tool a creation interface for a geometric model, whereas the GeometricModels DLL Class would allow that created model to actually be applied to (i.e., transform) imagery and vectors in IMAGINE. There is an established convention of giving related DLL Instances in these companion classes the same instance name. Because DLL instances in this DLL Class provide an interface with which a user may create a geometric model, each DLL instance will need to provide an interface through the EML scripting language as well as make use of the EML library in order to provide its services. In addition, constructing a GeomodelInterfaces DLL instance requires use of the ewrp package so that GUI and other information can be shared between the DLL and the application using the DLL. The available DLLs in the GeomodelInterfaces DLL Class will be identified by the class owner via the ERDAS_GEOMODEL_INTERFACES_PATH environment variable. The default value for this environment variable when running IMAGINE is: ERDAS_GEOMODEL_INTERFACES_PATH=”./GeomodelInterfaces:${PERSONAL}/ GeomodelInterfaces:$IMAGINE_HOME/usr/lib/${ARCHM}/GeomodelInterfaces”

Instances in Current Version The following instances of GeomodelInterfaces DLLs are distributed with the current version of IMAGINE: DLL Instance

Availability

GeomodelInterfaces

affine.dll

Essentials

File-based Affine Model

camera.dll

Advantage

Camera Model

landsat.dll

Advantage

Landsat Model

357

DLL Instance

Availability

GeomodelInterfaces

orthosar.dll

Advanced Radar Ortho

Radarsat Model ERS Model

poly.dll

Essentials

Nth Order Polynomial Model

reproject.dll

Essentials

Reprojection Model

rubbers.dll

Essentials

Rubber Sheeting Model

spot.dll

Advantage

SPOT Model

Interface Function Definitions The GeomodelInterfaces DLL Class inherits the DLLs interface, as it is derived from that DLL Class. The titles returned by the InstanceTitleListGet function required by the DLLs interface are used as the names of the models provided by a particular DLL instance. The interface functions defined by this class are included below. Prototypes for all interface functions are available to the users of the IMAGINE Toolkit via the header file /usr/include/emod_GeomodelInterfaces.h.

358

Interface Function IsFileAppropriate Syntax int IsFileAppropriate( int index, char *fileName )

/* Input */ /* Input */

Arguments

index Specifies the title index of the model against which fileName is to be checked for appropriateness.

fileName Specifies the name of the file which should be checked for appropriateness. Description The IsFileAppropriate function should determine whether the named file is appropriate for the model indicated by index (defined in this DLL instance). For example, if index is 0, fileName should be checked for appropriateness against the model corresponding to the first title returned by InstanceTitleListGet. If index is 1, fileName should be checked for appropriateness against the model corresponding to the second title returned by InstanceTitleListGet. Etc. Appropriateness might be determined by examining fileName for data necessary to create the model, such as ephemeris data from an airborne sensor. Return Value This function should return 1 if the file is appropriate. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

359

Interface Function ModelSupportsAutoCompute Syntax int ModelSupportsAutoCompute( void *model /* Input */ )

Arguments

model Specifies the model to query for the auto-compute capability. Description The ModelSupportsAutoCompute function should determine whether model supports automatic recalculation of a solution whenever a new GCP is added. Return Value This function should return 1 if model supports auto-compute. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

360

Interface Function ModelSupportsForwardPredict Syntax int ModelSupportsForwardPredict( void *model /* Input */ )

Arguments

model Specifies the model to query for the forward predict capability. Description The ModelSupportsForwardPredict function should determine whether model supports forward prediction. Return Value This function should return 1 if model supports forward prediction. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

361

Interface Function ModelSupportsReversePredict Syntax int ModelSupportsReversePredict( void *model /* Input */ )

Arguments

model Specifies the model to query for the reverse predict capability. Description The ModelSupportsReversePredict function should determine whether model supports reverse prediction. Return Value This function should return 1 if model supports reverse prediction. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

362

Interface Function ModelIsInvertable Syntax int ModelIsInvertable( void *model )

/* Input */

Arguments

model Specifies the model to query for the invert capability. Description The ModelIsInvertable function should determine whether the transformation that is the result of a solution to model can be inverted. Return Value This function should return 1 if model supports inversion. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

363

Interface Function ModelSupportsGCPs Syntax int ModelSupportsGCPs( void *model )

/* Input */

Arguments

model Specifies the model to query for GCP support. Description The ModelSupportsGCPs function should determine whether model in its current state must use ground control points in defining its transformation. If determination of this requires that the internal state of model be updated to reflect modifications made by the user through model’s user interface, only updates that relate to this determination should be internalized when this function is called. If this function indicates that ground control points may be used in defining the transformation for model, it is the DLL’s responsibility to obtain the ground control points via the ewrp_InputControlGet and ewrp_ReferenceControlGet functions prior to calculating a solution to the model. The interface functions that require a current solution to the model to be calculated when they are called will indicate such in their interface function definition. Return Value This function should return 1 if model supports GCPs. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

364

Interface Function ModelNeedsElevation Syntax int ModelNeedsElevation( void *model )

/* Input */

Arguments

model Specifies the model to query for GCP support. Description The ModelNeedsElevation function should determine whether model needs elevation values included in the ground control points used to define the transformation that represents its solution. If this function indicates that model needs elevation values, the matrix returned by the ewrp_ReferenceControlGet function will contain 3 coordinate dimensions (x, y, z) for the reference points. Otherwise, the matrix returned will contain only 2 coordinate dimensions (x, y). It does not make sense for model to return 0 from the ModelSupportsGCPs function and to return 1 from this function. Return Value This function should return 1 if model requires elevation data. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

365

Interface Function ModelNeedsReferenceProjection Syntax int ModelNeedsReferenceProjection( void *model /* Input */ )

Arguments

model Specifies the model to be reset. Description The ModelNeedsReferenceProjection function should determine whether model needs a reference projection in order to define the transformation that represents its solution. If model needs to know the reference projection, this is an indication to the class owner that the model needs to be resolved when the reference projection changes. If this function indicates that knowledge of the reference projection is required for defining the transformation for model, it is the DLL’s responsibility to obtain the relevant reference projection information via the ewrp_RefProparmGet and/or ewrp_RefUnitsGet functions prior to calculating a solution to the model. The interface functions that require a current solution to the model to be calculated when they are called will indicate such in their interface function definition. Return Value This function should return 1 if model requires a reference projection. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

366

Interface Function ModelIsFileBased Syntax void ModelIsFileBased( void *model )

/* Input */

Arguments

model Specifies the model to be queried for a file basis. Description The ModelIsFileBased function should determine whether model is file based. File based models allow transformation from one pixel coordinate system to another without requiring any knowledge of a map system that may be associated with the input pixel coordinate system. If a model is file based, a geometric correction tool will try to preserve any map system information associated with the input during resampling. If, on the other hand, it is desired to calibrate the input pixel coordinate system with the transformation derived from a file based model, the original map system information associated with the input pixel coordinate system must be discarded. Return Value This function should return 1 if model is file based. Otherwise, 0 should be returned. Requirements This function is optional. If this function is not supplied by a DLL instance, a model of any title supported by that instance will be assumed to not be file based.

367

Interface Function ModelCreate Syntax void * ModelCreate( int Ewrp_WarpInfo )

index, *warpinfo

/* Input */ /* Input */

Arguments

index Specifies the title index of the model which is to be created.

warpinfo Specifies the context of the geometric model creation. Description The ModelCreate function should create a new model of type index.

index indicates which model defined by this DLL is to be created. index = 0 indicates that the model corresponding to the first title returned by the InstanceTitleListGet function is to be created, index = 1 indicates the second such model, etc. If warpinfo is non-NULL, any model created through this function must be able to display a model properties dialog when the ModelPropertiesDisplay function is called. This model properties dialog should be an EML script based dialog that is derived from the properties dialog of the GeomodelInterfaces interface template, GeomodelInterfaces.eml. Modification of the interface template to support this model should be confined to additions of frames and frame parts. No parts should be deleted or renamed in adapting the template to support the model. This function should use eeml_ParseVa to parse the EML script file containing the user interface for this model. The translation table passed to the eeml_ParseVa function call should include the contents of the translation table obtained from the ewrp_TranslationTableGet function. This table contains translations for application functions referenced in the template. The Eui_RootPart * passed to eeml_ParseVa should be derived from the Eui_Root * returned from the ewrp_EmlRootGet function call. This routine should also call routines from the ewrp package to set information in warpinfo

368

after the script has been parsed. These calls should include: ewrp_ModelInfoSet to set a pointer to the created model (the return value of this function) inside warpinfo. ewrp_ParseResultSet to set the parse result returned from eeml_ParseVa inside warpinfo. It is also common for this function to call the ewrp_InputfilenameGet function in DLL instances supporting models that require ephemeris data associated with the imagery upon which the model is being based. Return Value This function should return a created model (a void *) upon success. NULL should be returned on failure. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

369

Interface Function ModelDestroy Syntax void ModelDestroy( void *model )

/* Input */

Arguments

model Specifies the model to be destroyed. Description The ModelDestroy function should free all resources associated with model that were allocated by the ModelCreate or ModelConvertFromMIF function and any subsequent functions that operated on model. Return Value This function is of type void. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

370

Interface Function ModelConvertToMIF Syntax unsigned char * ModelConvertToMIF( void *model, Emif_Design **design, long *size )

/* Input */ /* Output */ /* Output */

Arguments

model Specifies the model to be converted to MIF format.

design Returns a MIF design describing the returned MIF object.

size Returns the size of the returned MIF object. Description The ModelConvertToMIF function should convert the portion of model that is required to fully identify and reconstruct model into machine-independent format (see emif). In other words, the MIF object returned from this function call should be able to be used as an argument to the ModelConvertFromMIF function so that the return value is equivalent to model. Prior to converting model to MIF, this function should update the internal representation of model so that it is consistent with any modifications made through its user interface (see ModelReset). Return Value This function should return the MIF form of model upon success. The size of the returned MIF object should be placed in *size and the MIF design that describes the MIF form of model should be placed in *design. If the function call fails, NULL should be returned and the caller will ignore *design and *size. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

371

Interface Function ModelConvertFromMIF Syntax void * ModelConvertFromMIF( int Ewrp_WarpInfo Emif_Design unsigned char )

index, *warpinfo, *design, *mifdata

/* /* /* /*

Input Input Input Input

*/ */ */ */

Arguments

index Specifies the title index of the model which is to be created.

warpinfo Specifies the context of the geometric model creation. design Specifies the MIF design describing mifdata.

mifdata Specifies a MIF version of the model to be created. Description The ModelConvertFromMIF function should convert the machine-independent data passed in mifdata and described by design into a model that can be used as an argument to subsequent calls to interface functions that require a model.

index indicates which model defined by this DLL is to be created. index = 0 indicates that the model corresponding to the first title returned by the InstanceTitleListGet function is to be created, index = 1 indicates the second such model, etc. If warpinfo is non-NULL, any model created through this function must be able to display a model properties dialog when the ModelPropertiesDisplay function is called. Under this condition, therefore, this function should take the same steps as those defined for the ModelCreate interface function under the same condition. Return Value This function should return a created model (a void *) upon success. NULL should be returned on failure.

372

Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

373

Interface Function ModelPropertiesDisplay Syntax void ModelPropertiesDisplay( void *model )

/* Input */

Arguments

model Specifies the model for which properties are to be displayed. Description The ModelPropertiesDisplay function should display the current properties of model via an EML script based dialog (see ModelCreate). This is normally accomplished through an eeml_ShowPart function call. Return Value This function is of type void. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

374

Interface Function ModelPropertiesRemove Syntax void ModelPropertiesRemove( void *model )

/* Input */

Arguments

model Specifies the model whose properties dialog is to be un-displayed. Description The ModelPropertiesRemove function should un-display the current properties of model (see ModelPropertiesDisplay). This is normally accomplished through an eeml_PartHide function call. Return Value This function is of type void. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

375

Interface Function ModelReset Syntax void ModelReset( void *model )

/* Input */

Arguments

model Specifies the model to be reset. Description The ModelReset function should update any dialogs associated with model (e.g., the dialog displayed when the ModelPropertiesDisplay function is called) with information that reflects the current internal state of the model. In general, modifications to a model’s properties should not be obtained and internalized as the changes are being made in the user interface, but rather are to be internalized only when the ModelSolve or ModelConvertToMIF functions are called. Return Value This function is of type void. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

376

Interface Function ModelElevationUpdate Syntax void ModelElevationUpdate( void *model )

/* Input */

Arguments

model Specifies the model whose internal elevation information is to be updated. Description The ModelElevationUpdate function should update elevation information through the ewrp interface. If update of this information requires that the internal state of model be updated to reflect modifications made by the user through model’s user interface, only updates that relate to this information should be internalized when this function is called. The ewrp functions that must be called in order to effect the update include ewrp_ElevFilenameSet, ewrp_ElevConstantSet, and ewrp_ElevUnitsSet. All function calls should be passed the same warpinfo parameter that should have been saved internally to model when the ModelCreate or ModelConvertFromMIF function was called to create model. Return Value This function is of type void. Requirements This function is optional. Only DLL instances supporting models requiring elevation information need to supply this function.

377

Interface Function ModelSolve Syntax int ModelSolve( void *model, int reportErr )

/* Input */ /* Input */

Arguments

model Specifies the model to be solved.

reportErr Specifies a boolean flag indicating whether model specific errors should be reported if the model cannot be solved. Description The ModelSolve function should determine whether enough information has been provided to solve model, i.e., to compute a transformation that reflects the current state of model. This determination should involve actually computing or attempting to compute the transformation and recording the success of this computation and any resulting transformation internally to model. If the reportErr flag is non-zero, this function should report errors through the eerr interface. Otherwise, any errors should be suppressed. Prior to solving model, this function should update the internal representation of model so that it is consistent with any modifications made through its user interface (see ModelReset). Return Value This function should return 1 if a geometric transformation solution could be computed for the given model. Otherwise, 0 should be returned. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

378

Interface Function ModelSolutionDelete Syntax void ModelSolutionDelete( void *model )

/* Input */

Arguments

model Specifies the model whose current solution is to be discarded. Description The ModelSolutionDelete function should un-remeber any solution computed by the ModelSolve function, i.e., any subsequent calls to ModelXFormGet should return a NULL transformation until another successful call to ModelSolve is made. Return Value This function is of type void. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

379

Interface Function ModelErrorDisplay Syntax void ModelErrorDisplay( void *model )

/* Input */

Arguments

model Specifies the model whose solution error is to be displayed. Description The ModelErrorDisplay function should compute the error for the solution of model and display the computed error in a dialog. Computation of any error is usually facilitated by accessing the input and reference control points through the ewrp_InputControlGet and ewrp_ReferenceControlGet functions. This function is responsible for setting the residuals via the ewrp_ResidualsSet function prior to returning. Return Value This function is of type void. Requirements This function is optional. If this function is supplied, the ModelErrorRemove function must also be supplied or this function will be ignored.

380

Interface Function ModelErrorRemove Syntax void ModelErrorRemove( void *model )

/* Input */

Arguments

model Specifies the model whose solution error display is to be un-displayed. Description The ModelErrorRemove function should un-display the model error dialog displayed by ModelErrorDisplay. Return Value This function is of type void. Requirements This function is optional. If this function is supplied, the ModelErrorDisplay function must also be supplied or this function will be ignored.

381

Interface Function ModelXFormGet Syntax int ModelXFormGet( void *model, char ***titles, void ***xForms )

/* Input */ /* Output */ /* Output */

Arguments

model Specifies the model whose solution is to be returned as a GeometricModels representation.

titles Returns an array of character string titles of the GeometricModels transformations returned in data.

xForms Returns an array of GeometricModels transformations (as void *), one for each title. Description The ModelXFormGet function should return the transformation currently contained in model (placed there through a successful call to ModelSolve). The GeomodelInterfaces DLL Class is primarily used to create a model. Inherent in a model that can be solved is a transformation. The model is specific to the parameters used to create the model, which may include ephemeris data, ground control points, etc. The transformation, on the other hand, is intended to be viewed by applications as generic and is simply used to transform coordinates from one coordinate system to another. Whereas the model is controlled by the GeomodelInterfaces DLL Class, the transformation is controlled by the GeometricModels DLL Class. Thus, creation of an instance of the GeomodelInterfaces Class involves some knowledge and collaboration with the GeometricModels DLL Class. Often, the collaboration involves actually defining a companion GeometricModels DLL instance that can handle the transformations delivered by this function. The DLL writer should bear in mind that if a companion GeometricModels DLL instance is constructed, the transformation of points through transformations handled by that DLL instance should be treated generically. In other words, even if the transformation has knowledge of the image

382

upon which the model that delivered that transformation was based, the transformation should extrapolate outside the image area to transform coordinates. Because applications are treating the transformation generically, undesired application behavior may result if the transformation delivers zeros for transformed coordinates when it senses that the input coordinates are outside the original image area. The DLL writer should also bear in mind that, by convention in IMAGINE, the entire valid image area is defined in the pixel coordinate system as extending from (-0.5, -0.5) to (w-0.5,h-0.5) where w and h are the width and height of the image in pixels, respectively. This function should place an array of char * in *titles and an array of void * in *xForms. Both arrays should be dynamically allocated, so as to be freeable by the caller. The contents of the arrays will NOT be freed by the caller. The titles returned in the *titles array should be valid titles for the GeometricModels DLL Class and the transformations passed back in *xForms should be valid transformations for their corresponding titles. In other words, the two arrays along with the count returned must be suitable arguments to the exfr_XFormDataSet function. If the DLL instance manipulates its transformations through the exfr package, the exfr_XFormDataGet function can be used to directly pass back the data required. As an example, in cases where a companion GeometricModels DLL instance is constructed to handle transformations delivered by the model, the returned count is usually 1 and the single title returned in the *titles array reflects the title handled by the companion GeometricModels DLL instance. The single transformation returned in *xForms contains data that is understandable by the companion GeometricModels DLL instance. Return Value This function should return the number of GeometricModels components returned (i.e., the length of the returned *titles and *xForms arrays). If the function fails, 0 should be returned. *titles and *xForms will be ignored by the caller in this case. Requirements This function is required. If this function does not exist, the DLL Instance will be ignored.

383

Interface Function XFormIsEditable Syntax int XFormIsEditable( char *title, void *xForm )

/* Input */ /* Input */

Arguments

title Specifies the GeometricModels title of a transformation to test for edit support.

xForm Specifies the GeometricModels transformation to test for edit support. Description The XFormIsEditable function should determine whether this DLL instance can edit the single component transformation, xForm, with title, title, using this DLL instances XFormEdit function. Return Value This function should return 1 if it can provide an edit interface to the specified transformation. Otherwise, 0 should be returned. Requirements This function is optional. If this function is supplied, the XFormEdit function must also be supplied or this function will be ignored.

384

Interface Function XFormEdit Syntax int XFormEdit( char *title, void **xForm )

/* Input */ /* In/Out */

Arguments

title Specifies the GeometricModels title of a transformation to be edited.

xForm Specifies the GeometricModels transformation to edit. Description The XFormEdit function should display an edit interface for the transformation, *xForm, whose GeometricModels title is title. The interface displayed should be a modal interface so that this interface function does not return until the edit is completed or cancelled. The edit should be completed in-place, if possible. The transformation is passed indirectly (as a void **) so that if it needs to be destroyed and re-created in order to be edited, the function interface accommodates this. Return Value This function should return 1 upon success and 0 for failure. Requirements This function is optional. If this function is supplied, the XFormIsEditable function must also be supplied or this function will be ignored.

385

DLL Class ApplicationFunctions Description The ApplicationFunctions DLL Class, derived from the DLLs DLL Class, provides a means of defining functions callable from within EML scripts on a session-wide basis. Refer to the Functions section of the EML Reference Manual for a description of calling functions from within an EML script. The initial specifications of EML defined built-in functions that are callable from any EML script regardless of the application that parsed the EML script. These functions are defined in the EML library that EML based applications rely on for their EML script interpreting ability. Though accessible session-wide, this list of functions is not easily extensible. Later specifications allowed this list of functions that were callable from within an EML script to be extended by allowing a function translation table to be supplied by an application to the EML library routine that parses an EML script for interpretation. Although this provided extensibility, the added functions were only usable from EML scripts that were parsed by the application that defined the functions. The ApplicationFunctions DLL Class allows functions to be introduced to an IMAGINE installation that are available session-wide. These functions can be called from any EML script, regardless of the application that is used to parse that EML script. The ApplicationFunctions class owner package, eeml_appfuncs, does not have a programmatic API. The class owner provides utility to the EML library by providing search and load functionality for all ApplicationFunctions DLLs. The functions discovered by the class owner are then made available to the EML script parser and interpreter when an application calls on the relevant EML Library functions to parse and interpret an EML script. Instances in Current Version The following instances of ApplicationFunctions DLLs are distributed with the current version of IMAGINE. DLL Instance builtin.dll

Description Application functions built-in to EML

Interface Function Definitions The ApplicationFunctions DLL Class currently defines no interface functions beyond

386

those defined in the DLLs DLL Class. The usefulness of this DLL Class comes from how the class owner uses the titles returned from the InstanceTitleListGet function. Namely, this list of titles is interpreted as a list of function names of global Eeml_AppFunction’s accessible in the DLL instance from which the list was obtained. If a given title is located as a global function symbol, a pointer to that function is placed in the translation table of the EML library. Otherwise, the title is ignored. Any given title must currently name an Eeml_AppFunction or the argument passing from the EML script to the function will not occur properly.

387

Function Pointer Type Eeml_AppFunction Typedef Estr_StringList * (*Eeml_AppFunction)( Eeml_Menu Emsc_Opaque long char Eerr_ErrorReport )

menu, *context, argc, **argv, **err

/* /* /* /* /*

Input */ Input */ Input */ Input */ Output */

Arguments

menu This parameter is obsolete.

context Specifies the context of the application function call. This is currently always NULL for application functions retrieved from an ApplicationFunctions DLL instance. argc Specifies the argument count.

argv Specifies an array of argc character string arguments.

err Returns an error condition. Description An Eeml_AppFunction defines a prototype for a function that is callable from within an EML script. All arguments to the function call in the EML script are converted to character strings and are represented by argc and argv in the called function. An Eeml_AppFunction may return values to the EML script through a returned Estr_StringList *. This would be accomplished by using the Eeml_AppFunction as a function rather than a function command as in the following EML excerpt: variable

x;

set x = myappfunc( $myarg1, $myarg2 );

388

Notes If the first item in the returned string list could be interpreted as a number, it should be enclosed in double quotes or the entire string list will be interpreted as a set of numbers. An Eeml_AppFunction should be defined to always return a string list (even if it is empty) or always return NULL. It should be used uniformly in EML scripts as either a function or a function command. Return Value The function returns an Estr_StringList *. The returned Estr_StringList *, if non-NULL, will be freed by the caller (regardless of the setting of *err). If the function call succeeds, *err should be set to NULL. If the function call fails *err should be set to reflect the error; the responsibility for the cleanup of the returned Eerr_ErrorReport * is assumed by the caller.

389