1
/******************************************************************************
3
* Purpose: Documentation for the PCIDSKFile class.
5
******************************************************************************
7
* PCI Geomatics, 50 West Wilmot Street, Richmond Hill, Ont, Canada
9
* Permission is hereby granted, free of charge, to any person obtaining a
10
* copy of this software and associated documentation files (the "Software"),
11
* to deal in the Software without restriction, including without limitation
12
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
13
* and/or sell copies of the Software, and to permit persons to whom the
14
* Software is furnished to do so, subject to the following conditions:
16
* The above copyright notice and this permission notice shall be included
17
* in all copies or substantial portions of the Software.
19
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
20
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25
* DEALINGS IN THE SOFTWARE.
26
****************************************************************************/
30
\fn PCIDSKInterfaces *PCIDSK::PCIDSKFile::GetInterfaces();
32
\brief Fetch hookable interfaces in use with this file.
35
******************************************************************************
37
\fn PCIDSKChannel *PCIDSK::PCIDSKFile::GetChannel( int band );
39
\brief Fetch channel interface object.
41
The returned channel object remains owned by the PCIDSKFile and should
42
not be deleted by the caller, and will become invalid after the PCIDSKFile is
45
@param band the band number to fetch (one based).
47
@return pointer to internally managed channel object.
49
******************************************************************************
51
\fn PCIDSKSegment *PCIDSK::PCIDSKFile::GetSegment( int segment );
53
\brief Fetch segment interface object.
55
The returned segment object remains owned by the PCIDSKFile and should
56
not be deleted by the caller, and will become invalid after the PCIDSKFile is
59
@param segment the segment number to fetch (one based).
61
@return pointer to internally managed segment object.
63
******************************************************************************
65
\fn PCIDSKSegment *PCIDSK::PCIDSKFile::GetSegment( int type, std::string name, int previous = 0 );
67
\brief Fetch segment interface object.
69
If available, a segment of the specified type and name is returned. The
70
search is started after segment "previous" if none-zero.
72
The returned segment object remains owned by the PCIDSKFile and should
73
not be deleted by the caller, and will become invalid after the PCIDSKFile is
76
@param type the segment type desired, or SEG_UNKNOWN for any type.
78
@param name the segment name or "" for any name.
80
@param previous segment after which the search should start or 0 (default) to
83
@return pointer to internally managed segment object or NULL if none correspond
86
******************************************************************************
88
\fn int PCIDSK::PCIDSKFile::GetWidth() const
90
\brief Fetch image width.
92
@return the width of the file in pixels.
94
******************************************************************************
96
\fn int PCIDSK::PCIDSKFile::GetHeight() const
98
\brief Fetch image height.
100
@return the height of the file in pixels.
102
******************************************************************************
104
\fn int PCIDSK::PCIDSKFile::GetChannels() const
106
\brief Fetch channel (band) count.
108
@return the number of channels on this file.
110
******************************************************************************
112
\fn const char *PCIDSK::PCIDSKFile::GetInterleaving() const
114
\brief Fetch file interleaving method.
116
@return the interleaving name, one of "PIXEL", "BAND" or "FILE". Note that
117
tiled files will be reported as "FILE" interleaving.
119
******************************************************************************
121
\fn bool PCIDSK::PCIDSKFile::GetUpdatable() const
123
\brief Check readonly/update status.
125
@return true if the file is open for update, or false if it is read-only.
127
******************************************************************************
129
\fn uint64 PCIDSK::PCIDSKFile::GetFileSize() const
131
\brief Fetch file size.
133
@return returns the size of the PCIDSK file in bytes, as recorded in the
136
******************************************************************************
138
\fn void PCIDSK::PCIDSKFile::WriteToFile( const void *buffer, uint64 offset, uint64 size);
140
\brief Write data to file.
142
This method is normally only used by the PCIDSK library itself, and provides
143
a mechanism to write directly to the PCIDSK file. Applications should normally
144
use the PCIDSK::PCIDSKChannel::ReadBlock(), and
145
PCIDSK::PCIDSKChannel::WriteBlock() methods for imagery, or appropriate
146
PCIDSK::PCIDSKSegment methods for updating segment data.
148
@param buffer pointer to the data to write to disk.
149
@param offset the byte offset in the file (zero based) at which to write the data.
150
@param size the number of bytes from buffer to write.
152
******************************************************************************
154
\fn void PCIDSK::PCIDSKFile::ReadFromFile( void *buffer, uint64 offset, uint64 size);
156
\brief Read data from file.
158
This method is normally only used by the PCIDSK library itself, and provides
159
a mechanism to read directly from the PCIDSK file. Applications should normally
160
use the PCIDSK::PCIDSKChannel::ReadBlock() method for imagery, or appropriate
161
PCIDSK::PCIDSKSegment methods for reading segment data.
163
@param buffer pointer to the buffer into which the data should be read.
164
@param offset the byte offset in the file (zero based) at which to read the data.
165
@param size the number of bytes from the file to read.
167
******************************************************************************
169
\fn void PCIDSK::PCIDSKFile::GetIODetails( void ***io_handle_pp, Mutex ***io_mutex_pp, const char *filename = "" );
171
\brief Fetch details for IO to named file.
173
This method is normally only used by the PCIDSK library itself to request
174
io accessors for a file. If filename is empty, accessors for the PCIDSK file
175
are returned. Otherwise accessors for a dependent file (ie. FILE linked
178
@param io_handle_pp pointer to a pointer into which to load the IO handle.
180
@param io_mutex_pp pointer to a pointer into which to load the associated mutex.
182
@param filename the name of the file to access or an empty string for the PCIDSK
185
******************************************************************************
187
\fn int PCIDSK::PCIDSKFile::GetPixelGroupSize() const;
189
\brief fetch number of bytes per pixel
191
Returns the number of bytes for each pixel group. Each pixel group
192
consists of the values for all the channels in the file in order.
194
@note This method should only be called for GetInterleaving() == "PIXEL" files.
196
@return the size of a pixel group in bytes.
198
@see ReadAndLockBlock()
200
******************************************************************************
202
\fn uint8 *PCIDSK::PCIDSKFile::ReadAndLockBlock( int block_index, int win_xoff=-1, int win_xsize=-1 );
206
Returnst the pointer to an internal buffer for the indicated block. The
207
buffer is owned by the PCIDSKFile object, but will be considered locked
208
and available for the application code to read and modify until the
209
UnlockBlock() method is called. The buffer will contain all the pixel values
210
for the requested block in pixel interleaved form.
212
The win_xoff, and win_xsize parameters may be used to select a subregion of
213
the scanline block to read. By default the whole scanline is read.
215
@note This method should only be called for GetInterleaving() == "PIXEL"
216
files. Normal imagery access should be via the PCIDSKChannel class. This
217
method is provided on the PCIDSKFile for pixel interleaved files to allow
218
optimized access for this one case.
220
@param block_index the zero based block(scanline) to be read.
222
@param win_xoff the offset into the scanline to start reading values.
224
@param win_xsize the number of pixels to read.
226
@return pointer to an internal buffer with pixel data in it.
228
******************************************************************************
230
\fn void PCIDSK::PCIDSKFile::UnlockBlock( bool mark_dirty=false);
234
This method should be called after use of the buffer from ReadAndLockBlock()
235
is complete. If the buffer was modified and will need to be written to disk
236
the argument "mark_dirty" should be passed in as true.
238
@note This method should only be called for GetInterleaving() == "PIXEL" files.
240
@param mark_dirty true if the block data was modified, else false.
242
@see ReadAndLockBlock()
244
******************************************************************************
246
\fn void PCIDSK::PCIDSKFile::FlushBlock();
248
\brief force write of dirty buffer
250
This method may be used for force the flushing of any previously modified
251
pixel data for the current pixel interleaved scanline to disk. The imagery
252
buffer is that returned by ReadAndLockBlock(), and the data would have had
253
to have been marked dirty when UnlockBlock() was called.
255
Dirty data will be automatically flushed to disk on file close, or when
256
another block is read with ReadAndLockBlock(). This method is primarily used
257
to force flushing to disk without closing the file.
259
@note This method should only be called for GetInterleaving() == "PIXEL" files.
261
@see ReadAndLockBlock()
263
******************************************************************************
264
\fn std::vector<std::string> PCIDSK::PCIDSKFile::GetMetadataKeys();
266
\brief Fetch metadata keys
268
Returns a vector of metadata keys that occur on this object. The values
269
associated with each may be fetched with GetMetadataValue().
273
@see GetMetadataValue()
275
******************************************************************************
276
\fn std::string PCIDSK::PCIDSKFile::GetMetadataValue( std::string key );
278
\brief Fetch metadata value
280
Fetch the metadata value associated with the passed key on this object. If
281
there is no such item an empty string is returned.
283
@param key the key to fetch the value for.
285
@return the value of the indicated metadata item, or an empty string if it
286
does not exist on the target object.
288
@see GetMetadataKeys()
290
******************************************************************************
291
\fn void PCIDSK::PCIDSKFile::SetMetadataValue( std::string key, std::string value );
293
\brief Set metadata value
295
Assign the metadata value associated with the passed key on this object.
296
The file needs to be open for update. Note that keys should be well formed
297
tokens (no special characters, spaces, etc).
299
@param key the key to fetch the value for.
301
@param value the value to assign to the key. An empty string deletes the item.
303
@see GetMetadataValue()
305
******************************************************************************
306
\fn void PCIDSK::PCIDSKFile::CreateOverviews( int chan_count, int *chan_list, int factor, std::string resampling );
308
\brief Create an overview level
310
An overview is created on the indicated list of channels. If chan_count is
311
zero, then it will be created for all channels on the file. The overview will
312
have a size determined by dividing the base image level by "factor". The
313
file needs to be open in update mode.
315
If the requested overview level already exists an exception will be thrown.
317
While this function creates the overview level, and records the resampling
318
method in metadata, it does not actually compute and assign imagery to the
319
overview. This must be done externally by the application. Overview
320
computation is not a function of the PCIDSK SDK.
322
@param chan_count the number of channels listed in chan_list.
324
@param chan_list the channels for which the overview level should be created.
326
@param factor the overview decimation factor.
328
@param resampling the resampling to be used for this overview - one of "NEAREST", "AVERAGE" or "MODE".
330
******************************************************************************
331
\fn int PCIDSK::PCIDSKFile::CreateSegment( std::string name, std::string description, eSegType seg_type, int data_blocks );
333
\brief create a new auxiliary segment
335
A new segment of the desired type is created and assigned the given name and
336
description. The segment number is returned. The segment is created with the
337
requested number of data blocks. If this is zero a default size may be
338
assigned for some types with fixed sizes.
340
This method may fail if there are no unused segment pointers available in
343
@param name segment name, at most eight characters.
345
@param description segment description, at most 64 characters.
347
@param seg_type the segment type.
349
@param data_blocks the number of data blocks the segment should be initially assigned. If zero a default value may be used for some fixed sized segments.
351
@return the number of the segment created.
353
******************************************************************************
354
\fn int PCIDSK::PCIDSKFile::DeleteSegment( int segment );
356
\brief delete an existing segment
358
Delete the indicated segment number. The segment must currently exist. The
359
internal PCIDSKSegment object associated with this segment will also be
360
destroyed, and any references to it from GetSegment() or other sources should
361
not be used by the application after this call is made.
363
@param segment the number of the segment to delete from the file.
365
******************************************************************************
366
\fn void PCIDSK::PCIDSKFile::Synchronize();
368
\brief Write pending information to disk.
370
Some write and update operations on PCIDSK files are not written to disk
371
immediately after write calls. This method will ensure that any pending
372
writes are flushed through to disk. This includes writing updates to
373
tiled layer indexes, flushing out metadata, and potential caching of other
374
information such as vector writes.
376
NOTE: Currently this method does not invalidate read-cached information
377
such as segment pointer lists, segment headers, or band metadata. At some
378
point in the future it might be extended to do this as well.
added
removed
frmts/pcidsk/sdk/pcidskfile.dox
