edb.h File Reference

Constants and structures for the EDB file format. More...

#include "eaarlio/error.h"
#include "eaarlio/memory.h"
#include "eaarlio/stream.h"
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	eaarlio_edb_record
	EDB record. More...
struct	eaarlio_edb
	EDB index data. More...

Macros
#define	eaarlio_edb_record_empty()
	Empty eaarlio_edb_record value. More...
#define	eaarlio_edb_empty()
	Empty eaarlio_edb value. More...

Functions
eaarlio_error	eaarlio_edb_free (struct eaarlio_edb *edb, struct eaarlio_memory *memory)
	Free memory allocated to fields in eaarlio_edb. More...
eaarlio_error	eaarlio_edb_read (struct eaarlio_stream *stream, struct eaarlio_edb *edb, struct eaarlio_memory *memory, int include_records, int include_files)
	Read an entire EDB file. More...
eaarlio_error	eaarlio_edb_write (struct eaarlio_stream *stream, struct eaarlio_edb const *edb)
	Write an EDB file. More...

Detailed Description

Constants and structures for the EDB file format.

EDB stands for "EAARL database". The files are also sometimes called "index files" and have the corresponding file extension ".idx". The EDB file serves as an index into a set of raw lidar TLD files. The raw lidar TLD records do not have a fixed size, so the EDB file provides the information necessary to support random-access retrieval of TLD records.

The records in the EDB also define the raster numbers for the data. Although the TLD records contain a raster field, it is not used as it cycles. Instead, the one-based index of a record in the EDB is defined as its raster number. For example, the TLD record that corresponds with the 20th record in the EDB is defined to be raster 20.

The EDB file consists of an EDB header, followed by a series of EDB records, followed by a series of length-prefixed file names.

---

Data Structure Documentation

eaarlio_edb_record

struct eaarlio_edb_record

EDB record.

An EDB file contains one record for each raster in its associated set of TLD files.

Examples:

example_edb_read.c, and example_edb_write.c.

Data Fields
uint8_t	digitizer	Digitizer used: 0 or 1.
int16_t	file_index	Index into eaarlio_edb::files for this record's TLD file.
uint8_t	pulse_count	Number of pulses in this raster.
uint32_t	record_length	Byte length of this record (including the header)
uint32_t	record_offset	Byte offset in TLD file to this record.
uint32_t	time_fraction	Fractional seconds component of timestamp. Use eaarlio_units_edb_time to derive floating point time
uint32_t	time_seconds	Integer seconds component of timestamp. Use eaarlio_units_edb_time to derive floating point time

eaarlio_edb

struct eaarlio_edb

EDB index data.

This structure represents the data from an EDB file. Correspondingly, it's the in-memory representation of the index.

Examples:

eaarlio_yaml.c, example_edb_read.c, and example_edb_write.c.

Data Fields
uint32_t	file_count	Number of files in eaarlio_edb::files.
char **	files	Names of the TLD files.
uint32_t	record_count	Number of records in eaarlio_edb::records.
struct eaarlio_edb_record *	records	Record entries for the TLD rasters.

Macro Definition Documentation

eaarlio_edb_empty

#define eaarlio_edb_empty

(

)

Value:

(struct eaarlio_edb)                                                       \
    {                                                                          \
        0, 0, NULL, NULL                                                       \
    }

Empty eaarlio_edb value.

All numeric fields will contain zero values. All pointers will be NULL.

Examples:

example_edb_read.c, and example_edb_write.c.

eaarlio_edb_record_empty

#define eaarlio_edb_record_empty

(

)

Value:

(struct eaarlio_edb_record)                                                \
    {                                                                          \
        0, 0, 0, 0, 0, 0, 0                                                    \
    }

Empty eaarlio_edb_record value.

All fields will contain zero values.

Examples:

example_edb_read.c.

Function Documentation

eaarlio_edb_free()

eaarlio_error eaarlio_edb_free	(	struct eaarlio_edb *	edb,
		struct eaarlio_memory *	memory
	)

Free memory allocated to fields in eaarlio_edb.

On success:

Parameters

[in,out]	edb	EDB with memory to release
[in]	memory	Memory handler, or NULL for stdlib

Returns

On success, EAARLIO_SUCCESS.

On failure, eaarlio_error representing the failure condition.

Postcondition

On success, edb->records and edb->files will be null.

On success, any memory that was allocated for edb->records or edb->files has been released.

Remarks

The pointer to edb is not released.

Pointer fields may be NULL. If so, they are left alone.

Examples:

example_edb_read.c.

eaarlio_edb_read()

eaarlio_error eaarlio_edb_read	(	struct eaarlio_stream *	stream,
		struct eaarlio_edb *	edb,
		struct eaarlio_memory *	memory,
		int	include_records,
		int	include_files
	)

Read an entire EDB file.

Parameters

[in]	stream	Stream with data to read
[out]	edb	Pointer to EDB index to be populated
[in]	memory	Memory handler, or NULL for stdlib
[in]	include_records	Should record data be read? 1 = yes, 0 = no
[in]	include_files	Should TLD filenames be read? 1 = yes, 0 = no

Returns

On success, EAARLIO_SUCCESS.

On failure, eaarlio_error representing the failure condition.

Postcondition

If edb->records is not null, then it points to newly allocated memory.

If edb->filenames is not null, then it points to newly allocated memory.

If edb->filenames is not null, then each non-null entry in it points to newly allocated memory.

On success:

• edb->record_count and edb->file_count are populated.
• if include_records = 1, then edb->records will be populated.
• if include_records = 0, then edb->records will be NULL.
• if include_files = 1, then edb->files will be populated.
• if include_files = 0, then edb->files will be NULL.

On failure, edb->records and edb->files may be partially populated. Anything not populated will be null.

Examples:

example_edb_read.c.

eaarlio_edb_write()

eaarlio_error eaarlio_edb_write	(	struct eaarlio_stream *	stream,
		struct eaarlio_edb const *	edb
	)

Write an EDB file.

Parameters

[in]	stream	Stream to be written to
[in]	edb	Pointer to EDB index to write

Returns

On success, EAARLIO_SUCCESS.

On failure, eaarlio_error representing the failure condition.

Postcondition

On success, the encoded data was written to stream.

Examples:

example_edb_write.c.