1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
CGATS file I/O library, V2.01 README file
-----------------------------------------
Package contents:
-----------------
cgatslib.zip ZIP archive of the following files
Readme.txt This file.
License.txt Important! - Permissions for use of this package.
cgats.c CGATS Library source code.
cgatsstd.c I/O and malloc source code.
cgats.h CGATS Library include file. Note machine dependent defines.
pars.c Parser source code.
parsstd.c I/O and malloc source code.
pars.h Parser include file. Note machine dependent defines.
Jampfile JAM style "makefile" see <http://www.perforce.com/jam/jam.html>
Makefile Makefile. Modify this to include one of the following rule sets.
Makefile.WNT Makefile defines for Microsoft C++ on Windows NT
Makefile.IBMNT Makefile defines for IBM C++ on Windows NT
Makefile.UNIX Makefile defines for generic UNIX system
Makefile.OSX Makefile defines for Apple MAC OSX
Changes:
--------
Changes since V2.00
Removed all exit()s from code - now return error values
from all functions.
Added abstract objects for File I/O and memory allocation
to improve system compatibility.
Separated the implimentations of the abstract I/O and
memory objects that ise stdio and malloc into separate
files so that a library can be compiled without reference
to these system calls.
---------------------------------------------------------------
DOCUMENTATION
This library has been implemented from the CGATS.5 Data Exchange Format
specification, in Annex J, of the ANSI CGATS.5-1993 standard.
See <http://www.npes.org/standards/description.htm>
This module attempts to make reading CGATS.5 and IT8.7 files
easy and convenient. Since the standard is a less than clear
on some points it is hard to know how much compatibility is
to be expected.
The module supports non-standard keywords and fields automatically.
It does not support reading of comments.
It supports reading and writing multiple tables within one file.
Abreviated tables may be written.
Non-standard fields written by this module will be recognized
correcty when read by this module (data types are written
unambiguously - reals all have a decimal point, no non-quoted strings
are written that could be interpreted as a real or integer), but
there is no certainty that non-standard fields written by other
software will be recognized corectly (e.g. - how to you tell
whether 1234 is an integer, real, or non-quoted string ?)
To creat a file each element needs to be built up in turn:
Create an empty cgats structure:
new_cgats().
A non-standard memory allocator can be specified for use
by the cgats object by passing an object that inherits
from the cgatsAlloc class defined in parse.h, to the
new_cgats_al(cgatsAlloc *al) constructor.
Use the module methods to:
Add a user defined file identifier to augment the standard identifiers:
add_other(cgats *p, char *osym)
This can be used to read or write table that are compatible with CGATS.5
syntax but have different file identifiers.
Use a zero length string (ie. just "") for wildcard.
Normaly returns 0, returns -ve if there was a system error,
& sets p->errc & p->err appropriately.
create an empty table entry:
add_table(cgats *p, table_type tt, int oi)
tt is the table type: it8_7_1, it8_7_2, it8_7_3, it8_7_4, cgats_5, cgats_X,
tt_other or tt_none.
cgat_X represents any "CGATS.XXX" table type.
If tt_other is used for creating a file, then oi must be set to the index of the
user defined table identifiers set by calls to p->add_other();
The table type read can be identified by looking at the index
p->t[table_number].tt, which will be set to the table type.
If the type is cgats_X type, the type actually found will be in p->cgats_type.
If tt == tt_other, then the "other index" value is p->t[table_numberx].oi.
For a wildcard tt_other, the actual type found will be at p->others[oi].
Tables are added in turn, and are indexed from 0 in other functions.
Returns 0 normally.
It returns -2 if there was a system error, & sets p->errc & p->err appropriately.
Suppress the writing of the file identifier string, standard keyword definitions
and/or field definitions for a second or subsequent table:
set_table_flags(cgats *p, int table, int sup_id, int sup_kwords, int sup_fields);
This only makes sense if the subsequent table has the same identifier type, keywords
and field definitions as the preceding table. Returns 0 normally.
It returns -1 if there was an error, & sets p->errc & p->err appropriately.
Add keywords and their values:
int add_kword(cgats *p, int table, char *ksym, char *kdata, char *kcom);
The return value is the index of the new keyword, or -1, errc & err on error.
Any non-standard keywords will automatically be declared in the file.
The comment is optional and NULL should be passed if no comment is to be used
after the keyword/value pair.
Standard keywords are:
ORIGINATOR System, organization or individual that created data
DESCRIPTOR Purpose or contents of the data file
CREATED Date of creation of the file
MANUFACTURER Manufacturer of physical target
PROD_DATE Year and month of physical target production yyyy:mm
SERIAL Unique physical target serial number
MATERIAL Material physical target was produced on
INSTRUMENTATION Manufacturer and model number of measuring instrument
MEASUREMENT_SOURCE Illumination used for spectral measurements
PRINT_CONDITIONS Characteristics of printed sheet being reported
Standard keywords will be created automatically if necessary for a legal file format.
The following kewords are supplied automatically by the module,
and cannot be used for other things:
NUMBER_OF_FIELDS
BEGIN_DATA_FORMAT
END_DATA_FORMAT
NUMBER_OF_SETS
BEGIN_DATA
END_DATA
KEYWORD
Add fields:
int add_field(cgats *p, int table, char *fsym, data_type ftype);
The return value is the index of the new field, or return
-1, errc & err on error, -2, errc & err on system error.
ftype defines the data type from: r_t, i_t, cs_t, nqcs_t.
r_t is the real (double) type,
i_t is the integer (int) type,
cs_t is the character string (char*) type,
nqcs_t is the same as cs_t except that it will be non-quoted if possible.
Note that the type must agree with the standard type if the field is
from the set default data format identifiers:
SAMPLE_ID nqcs_t Identifies sample which data represents
STRING cs_t Identifies label, or other non-machine readable value.
CMYK_C r_t Cyan percentage of CMYK
CMYK_M r_t Magenta percentage of CMYK
CMYK_Y r_t Yellow percentage of CMYK
CMYK_K r_t Black percentage of CMYK
D_RED r_t Red filter reflection density
D_GREEN r_t Green filter reflection density
D_BLUE r_t Blue filter reflection density
D_VIS r_t Visual filter reflection density
RGB_R r_t Red component of RGB data
RGB_G r_t Green component of RGB data
RGB_B r_t Blue component of RGB data
SPECTRAL_NM r_t Wavelength of measurement in nanometers
SPECTRAL_PCT r_t Precentage reflectance/transmittance
XYZ_X r_t X component of tristimulus data
XYZ_Y r_t Y component of tristimulus data
XYZ_Z r_t Z component of tristimulus data
XYY_X r_t x component of chromaticity data
XYY_Y r_t y component of chromaticity data
XYY_CAPY r_t Y component of chromaticity data
LAB_L r_t L* component of Lab data
LAB_A r_t a* component of Lab data
LAB_B r_t b* component of Lab data
LAB_C r_t C*ab component of Lab data
LAB_H r_t hab component of Lab data
LAB_DE r_t CIA delta E
STDEV_X r_t Standard deviation of X (tristimulous data)
STDEV_Y r_t Standard deviation of Y (tristimulous data)
STDEV_Z r_t Standard deviation of Z (tristimulous data)
STDEV_L r_t Standard deviation of L*
STDEV_A r_t Standard deviation of a*
STDEV_B r_t Standard deviation of b*
STDEV_DE r_t Standard deviation of CIE delta E
Add a set of data:
add_set(cgats *p, int table, ...)
The data should be supplied as a varargs list in the appropropriate
data format [char*, double or int].
Returns 0 normally, -1 errc & err if parameter error,
-2 errc & err if system error.
Add a set of data from union array:
add_setarr(cgats *p, int table, cgats_set_elem *args);
The data should be supplied as an array of cgats_set_elem unions.
Returns 0 normally, -1 errc & err if parameter error,
-2 errc & err if system error.
Write the data out to a file.
write_name(cgats *p, char *fname);
The method will return non-zero on an error, with an error
description in the err location of the structure.
A non-standard destination of data can be read by passing an
object that inherits from the cgatsFile class defined in
parse.h to the write(cgats *p, cgatsFile *fp) method.
To read in a data file, the cgats structure should be created
as usual. The read method can then be called to read in the file:
read_name(cgats *p, char *fname)
Returns 0 normally, and -ve on an error, with an error
description in the err location of the structure,
and errc set with the return code.
A non-standard source of data can be read by passing an
object that inherits from the cgatsFile class defined in
parse.h to the read(cgats *p, cgatsFile *fp) method.
The reader will deal automaticaly with carry over of keywords
and/or field definitions from one table to another, making each
table appear independent once read.
The data is accessed by refering to the following read-only
structure entries:
The number of tables will be in p->ntables
The number of keywords will be in p->t[table_number].nkwords
The number of fields will be in p->t[table_number].nfields
The number of sets will be in p->t[table_number].nsets
Tables, keywords, fields and sets index from 0.
The keywords will be in
p->t[table_number].ksym[keyword_index]
The keywords character string value be in
p->t[table_number].kdata[keyword_index]
The field format identifiers of each field will be in
p->t[table_number].fsym[field_index]
The data type of each field will be in
p->t[table_number].ftype[field_index]
A void pointer to the data of each field of each set will be in
p->t[table_number].fdata[set_index][field_index]
Cast the void pointet according to its type to retrieve the data.
Alternatively the
p->get_setarr(struct _cgats *p, int table, int set_index, cgats_set_elem *ary)
method can be used to fill in a suitable sized cgats_set_elem array with
the value of all the fields at a particular index. Any character string
type will be a pointer to the data in p->t[table_number].fdata[set_index][field_index].
To find the index to a particular keyword, use:
find_kword(cgats *p, int table, char *ksym)
-1 will be returned if no match is found.
-2 will be returned, p->errc & p->err will be set if table is out of range.
To find the index to a particular field, use:
find_field(cgats *p, int table, char *fsym);
-1 will be returned if no match is found.
-2 will be returned, p->errc & p->err will be set if table is out of range.
Rather than checking the error return codes from every method,
the first error is "sticky", and recorded in the object.
This can be checked after a series of operations by calling
the error(cgats *p, char **mes) method, which will return the
error code, and (optionaly) the error message.
Once operations are finished, the object can be deleted by calling
the delete method:
del(cgats *p)
Graeme Gill.
---------------------------------------------------------------
|