1
/******************************************************************************
4
* Project: libLAS - http://liblas.org - A BSD library for LAS format data.
5
* Purpose: LAS header class
6
* Author: Mateusz Loskot, mateusz@loskot.net
8
******************************************************************************
9
* Copyright (c) 2010, Mateusz Loskot
10
* Copyright (c) 2008, Phil Vachon
12
* All rights reserved.
14
* Redistribution and use in source and binary forms, with or without
15
* modification, are permitted provided that the following
18
* * Redistributions of source code must retain the above copyright
19
* notice, this list of conditions and the following disclaimer.
20
* * Redistributions in binary form must reproduce the above copyright
21
* notice, this list of conditions and the following disclaimer in
22
* the documentation and/or other materials provided
23
* with the distribution.
24
* * Neither the name of the Martin Isenburg or Iowa Department
25
* of Natural Resources nor the names of its contributors may be
26
* used to endorse or promote products derived from this software
27
* without specific prior written permission.
29
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
30
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
31
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
32
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
33
* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
34
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
35
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
36
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
37
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
38
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
39
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
41
****************************************************************************/
43
#ifndef LIBLAS_LASHEADER_HPP_INCLUDED
44
#define LIBLAS_LASHEADER_HPP_INCLUDED
46
#include <liblas/guid.hpp>
47
#include <liblas/bounds.hpp>
48
#include <liblas/schema.hpp>
49
#include <liblas/spatialreference.hpp>
50
#include <liblas/variablerecord.hpp>
51
#include <liblas/version.hpp>
52
#include <liblas/external/property_tree/ptree.hpp>
53
#include <liblas/export.hpp>
54
#include <liblas/detail/singleton.hpp>
56
#include <boost/cstdint.hpp>
57
#include <boost/foreach.hpp>
68
/// Definition of public header block.
69
/// The header contains set of generic data and metadata
70
/// describing a family of ASPRS LAS files. The header is stored
71
/// at the beginning of every valid ASPRS LAS file.
73
/// \todo TODO (low-priority): replace static-size char arrays as data members
74
/// with std::string and return const-reference to string object.
80
/// Official signature of ASPRS LAS file format, always \b "LASF".
81
static char const* const FileSignature;
83
/// Default system identifier used by libLAS, always \b "libLAS".
84
static char const* const SystemIdentifier;
86
/// Default software identifier used by libLAS, always \b "libLAS X.Y".
87
static char const* const SoftwareIdentifier;
89
/// Array of 5 elements - numbers of points recorded by each return.
90
/// \todo TODO: Consider replacing with {boost|std::tr1}::array<T, 5> --mloskot
91
typedef std::vector<boost::uint32_t> RecordsByReturnArray;
93
/// Default constructor.
94
/// The default constructed header is configured according to the ASPRS
95
/// LAS 1.2 Specification, point data format set to 0.
96
/// Other fields filled with 0.
100
Header(Header const& other);
102
/// Assignment operator.
103
Header& operator=(Header const& rhs);
105
/// Comparison operator.
106
bool operator==(const Header& other) const;
108
/// Get ASPRS LAS file signature.
109
/// \return 4-characters long string - \b "LASF".
110
std::string GetFileSignature() const;
112
/// Set ASPRS LAS file signature.
113
/// The only value allowed as file signature is \b "LASF",
114
/// defined as FileSignature constant.
115
/// \exception std::invalid_argument - if invalid signature given.
116
/// \param v - string contains file signature, at least 4-bytes long
117
/// with "LASF" as first four bytes.
118
void SetFileSignature(std::string const& v);
120
/// Get file source identifier.
121
/// \exception No throw
122
boost::uint16_t GetFileSourceId() const;
124
/// Set file source identifier.
125
/// \param v - should be set to a value between 1 and 65535.
126
/// \exception No throw
128
/// \todo TODO: Should we warn or throw about type overflow when user passes 65535 + 1 = 0
129
void SetFileSourceId(boost::uint16_t v);
131
/// Get value field reserved by the ASPRS LAS Specification.
132
/// \note This field is always filled with 0.
134
/// \todo TODO: Should we warn or throw about type overflow when user passes 65535 + 1 = 0
135
boost::uint16_t GetReserved() const;
137
/// Set reserved value for the header identifier.
138
/// \param v - should be set to a value between 1 and 65535.
139
/// \exception No throw
140
void SetReserved(boost::uint16_t v);
142
/// Get project identifier.
143
/// \return Global Unique Identifier as an instance of liblas::guid class.
144
guid GetProjectId() const;
146
/// Set project identifier.
147
void SetProjectId(guid const& v);
149
/// Get major component of version of LAS format.
150
/// \return Always 1 is returned as the only valid value.
151
boost::uint8_t GetVersionMajor() const;
153
/// Set major component of version of LAS format.
154
/// \exception std::out_of_range - invalid value given.
155
/// \param v - value between eVersionMajorMin and eVersionMajorMax.
156
void SetVersionMajor(boost::uint8_t v);
158
/// Get minor component of version of LAS format.
159
/// \return Valid values are 0, 1, 2, 3.
160
boost::uint8_t GetVersionMinor() const;
162
/// Set minor component of version of LAS format.
163
/// \exception std::out_of_range - invalid value given.
164
/// \param v - value between eVersionMinorMin and eVersionMinorMax.
165
void SetVersionMinor(boost::uint8_t v);
167
/// Get system identifier.
168
/// Default value is \b "libLAS" specified as the SystemIdentifier constant.
169
/// \param pad - if true the returned string is padded right with spaces and
170
/// its length is 32 bytes, if false (default) no padding occurs and
171
/// length of the returned string is <= 32 bytes.
172
/// \return value of system identifier field.
173
std::string GetSystemId(bool pad = false) const;
175
/// Set system identifier.
176
/// \exception std::invalid_argument - if identifier longer than 32 bytes.
177
/// \param v - system identifiers string.
178
void SetSystemId(std::string const& v);
180
/// Get software identifier.
181
/// Default value is \b "libLAS 1.0", specified as the SoftwareIdentifier constant.
182
/// \param pad - if true the returned string is padded right with spaces and its length is 32 bytes,
183
/// if false (default) no padding occurs and length of the returned string is <= 32 bytes.
184
/// \return value of generating software identifier field.
185
std::string GetSoftwareId(bool pad = false) const;
187
/// Set software identifier.
188
/// \exception std::invalid_argument - if identifier is longer than 32 bytes.
189
/// \param v - software identifiers string.
190
void SetSoftwareId(std::string const& v);
192
/// Get day of year of file creation date.
193
/// \todo TODO: Use full date structure instead of Julian date number.
194
boost::uint16_t GetCreationDOY() const;
196
/// Set day of year of file creation date.
197
/// \exception std::out_of_range - given value is higher than number 366.
198
/// \todo TODO: Use full date structure instead of Julian date number.
199
void SetCreationDOY(boost::uint16_t v);
201
/// Set year of file creation date.
202
/// \todo TODO: Remove if full date structure is used.
203
boost::uint16_t GetCreationYear() const;
205
/// Get year of file creation date.
206
/// \exception std::out_of_range - given value is higher than number 9999.
207
/// \todo TODO: Remove if full date structure is used.
208
void SetCreationYear(boost::uint16_t v);
210
/// Get number of bytes of generic verion of public header block storage.
211
/// Standard version of the public header block is 227 bytes long.
212
boost::uint16_t GetHeaderSize() const;
214
/// Sets the header size. Note that this is not the same as the offset to
216
void SetHeaderSize(boost::uint16_t v);
218
/// Get number of bytes from the beginning to the first point record.
219
boost::uint32_t GetDataOffset() const;
221
/// Set number of bytes from the beginning to the first point record.
222
/// \exception std::out_of_range - if given offset is bigger than 227+2 bytes
223
/// for the LAS 1.0 format and 227 bytes for the LAS 1.1 format.
224
void SetDataOffset(boost::uint32_t v);
226
/// Get number of bytes from the end of the VLRs to the GetDataOffset.
227
boost::uint32_t GetHeaderPadding() const;
229
/// Set the number of bytes from the end of the VLRs in the header to the
230
/// beginning of point data.
231
/// \exception std::out_of_range - if given offset is bigger than 227+2 bytes
232
/// for the LAS 1.0 format and 227 bytes for the LAS 1.1 format.
233
void SetHeaderPadding(boost::uint32_t v);
235
/// Get number of variable-length records.
236
boost::uint32_t GetRecordsCount() const;
238
/// Set number of variable-length records.
239
void SetRecordsCount(boost::uint32_t v);
241
/// Get identifier of point data (record) format.
242
PointFormatName GetDataFormatId() const;
244
/// Set identifier of point data (record) format.
245
void SetDataFormatId(PointFormatName v);
247
/// The length in bytes of each point. All points in the file are
248
/// considered to be fixed in size, and the PointFormatName is used
249
/// to determine the fixed portion of the dimensions in the point. Any
250
/// other byte space in the point record beyond the liblas::Schema::GetBaseByteSize()
251
/// can be used for other, optional, dimensions. If no schema is
252
/// available for the file in the form of a liblas.org VLR schema record,
253
/// These extra bytes are available via liblas::Point::GetExtraData().
254
boost::uint16_t GetDataRecordLength() const;
256
/// Get total number of point records stored in the LAS file.
257
boost::uint32_t GetPointRecordsCount() const;
259
/// Set number of point records that will be stored in a new LAS file.
260
void SetPointRecordsCount(boost::uint32_t v);
262
/// Get array of the total point records per return.
263
RecordsByReturnArray const& GetPointRecordsByReturnCount() const;
265
/// Set values of 5-elements array of total point records per return.
266
/// \exception std::out_of_range - if index is bigger than 4.
267
/// \param index - subscript (0-4) of array element being updated.
268
/// \param v - new value to assign to array element identified by index.
269
void SetPointRecordsByReturnCount(std::size_t index, boost::uint32_t v);
271
/// Get scale factor for X coordinate.
272
double GetScaleX() const;
274
/// Get scale factor for Y coordinate.
275
double GetScaleY() const;
277
/// Get scale factor for Z coordinate.
278
double GetScaleZ() const;
280
/// Set values of scale factor for X, Y and Z coordinates.
281
void SetScale(double x, double y, double z);
283
/// Get X coordinate offset.
284
double GetOffsetX() const;
286
/// Get Y coordinate offset.
287
double GetOffsetY() const;
289
/// Get Z coordinate offset.
290
double GetOffsetZ() const;
292
/// Set values of X, Y and Z coordinates offset.
293
void SetOffset(double x, double y, double z);
295
/// Get minimum value of extent of X coordinate.
296
double GetMaxX() const;
298
/// Get maximum value of extent of X coordinate.
299
double GetMinX() const;
301
/// Get minimum value of extent of Y coordinate.
302
double GetMaxY() const;
304
/// Get maximum value of extent of Y coordinate.
305
double GetMinY() const;
307
/// Get minimum value of extent of Z coordinate.
308
double GetMaxZ() const;
310
/// Get maximum value of extent of Z coordinate.
311
double GetMinZ() const;
313
/// Set maximum values of extent of X, Y and Z coordinates.
314
void SetMax(double x, double y, double z);
316
/// Set minimum values of extent of X, Y and Z coordinates.
317
void SetMin(double x, double y, double z);
319
/// Adds a variable length record to the header
320
void AddVLR(VariableRecord const& v);
323
VariableRecord const& GetVLR(boost::uint32_t index) const;
325
/// Returns all of the VLRs
326
const std::vector<VariableRecord>& GetVLRs() const;
328
/// Removes a VLR from the the header.
329
void DeleteVLR(boost::uint32_t index);
330
void DeleteVLRs(std::string const& name, boost::uint16_t id);
332
/// Rewrite variable-length record with georeference infomation, if available.
333
void SetGeoreference();
335
/// Fetch the georeference
336
SpatialReference GetSRS() const;
338
/// Set the georeference
339
void SetSRS(SpatialReference& srs);
341
/// Returns the schema.
342
Schema const& GetSchema() const;
345
void SetSchema(const Schema& format);
347
/// Return the liblas::Bounds. This is a
348
/// combination of the GetMax and GetMin
349
/// (or GetMinX, GetMaxY, etc) data.
350
const Bounds<double>& GetExtent() const;
352
/// Set the liblas::Bounds. This is a
353
/// combination of the GetMax and GetMin
354
/// (or GetMinX, GetMaxY, etc) data, and it is equivalent to setting
355
/// all of these values.
356
void SetExtent(Bounds<double> const& extent);
358
/// Returns a property_tree that contains
359
/// all of the header data in a structured format.
360
liblas::property_tree::ptree GetPTree() const;
362
/// Returns true iff the file is compressed (laszip),
363
/// as determined by the high bit in the point type
364
bool Compressed() const;
366
/// Sets whether or not the points are compressed.
367
void SetCompressed(bool b);
369
boost::uint32_t GetVLRBlockSize() const;
371
void to_rst(std::ostream& os) const;
372
void to_xml(std::ostream& os) const;
373
void to_json(std::ostream& os) const;
377
typedef detail::Point<double> PointScales;
378
typedef detail::Point<double> PointOffsets;
382
eDataSignatureSize = 2,
383
eFileSignatureSize = 4,
384
ePointsByReturnSize = 7,
387
eSoftwareIdSize = 32,
389
eFileSourceIdMax = 65535
392
// TODO (low-priority): replace static-size char arrays
393
// with std::string and return const-reference to string object.
396
// Private function members
401
// Private data members
403
char m_signature[eFileSignatureSize]; // TODO: replace with boost::array --mloskot
404
boost::uint16_t m_sourceId;
405
boost::uint16_t m_reserved;
406
boost::uint32_t m_projectId1;
407
boost::uint16_t m_projectId2;
408
boost::uint16_t m_projectId3;
409
boost::uint8_t m_projectId4[eProjectId4Size];
410
boost::uint8_t m_versionMajor;
411
boost::uint8_t m_versionMinor;
412
char m_systemId[eSystemIdSize]; // TODO: replace with boost::array --mloskot
413
char m_softwareId[eSoftwareIdSize];
414
boost::uint16_t m_createDOY;
415
boost::uint16_t m_createYear;
416
boost::uint16_t m_headerSize;
417
boost::uint32_t m_dataOffset;
418
boost::uint32_t m_recordsCount;
419
boost::uint32_t m_pointRecordsCount;
420
RecordsByReturnArray m_pointRecordsByReturn;
421
PointScales m_scales;
422
PointOffsets m_offsets;
423
Bounds<double> m_extent;
424
std::vector<VariableRecord> m_vlrs;
425
SpatialReference m_srs;
428
boost::uint32_t m_headerPadding;
431
LAS_DLL std::ostream& operator<<(std::ostream& os, liblas::Header const&);
433
/// Singleton used for all empty points upon construction. If
434
/// a reader creates the point, the HeaderPtr from the file that was
435
/// read will be used, but all stand-alone points will have EmptyHeader
437
class LAS_DLL DefaultHeader : public Singleton<Header>
445
DefaultHeader( DefaultHeader const&);
446
DefaultHeader& operator=( DefaultHeader const&);
451
} // namespace liblas
453
#endif // LIBLAS_LASHEADER_HPP_INCLUDED