C++ SimpleAPI Tutorial

This tutorial explains how to use the libE57 Simple API to do a basic read and write of lidar data encoded in the E57 format.

How to use E57SimpleAPI

The E57SimpleAPI is only available in source code. Follow the libe57 instructions for using the E57Foundation classes. Then add the E57Simple API source code to that build (E57Simple.cpp and E57SimpleImpl.cpp). The E57Simple API requires access to include/time_conversion/time_conversion.h and other dependences.

Reading using the E57 Simple API

Include required header files from the libE57 release.

	#include "E57Foundation.h"
	#include "E57Simple.h"

Instantiate an e57::Reader object and open the .e57 file.

	e57::Reader 	eReader("file.e57");

Read and access all the e57::Data3D header information from the first scan.

	int 		scanIndex = 0;	//picking the first scan
	
	e57::Data3D	scanHeader;		//read scan's header information
	eReader.ReadData3D( scanIndex, scanHeader);

	_bstr_t scanGuid = scanHeader.guid.c_str();		//get guid
	...

Get the size information about the scan.

	int64_t nColumn = 0;		//Number of Columns in a structure scan (from "indexBounds" if structure data)
	int64_t nRow = 0;			//Number of Rows in a structure scan	
	int64_t nPointsSize = 0;	//Number of points 
	int64_t nGroupsSize = 0;	//Number of groups (from "groupingByLine" if present)
	int64_t nCountsSize = 0;	//Number of points per group

	eReader.GetData3DSizes( scanIndex, nRow, nColumn, nPointsSize, nGroupsSize, nCounts, bColumnIndex);
	
	int64_t nSize = (nRow > 0) ? nRow : 1024;	//Pick a size for buffers

Setup the buffers and setup the e57::CompressedVectorReader point data object.

	double *xData = new double[nSize];
	double *yData = new double[nSize];
	double *zData = new double[nSize];

	e57::CompressedVectorReader dataReader = eReader.SetUpData3DPointsData(
		scanIndex, 	//!< scan data index 
		nSize, 		//!< size of each of the buffers given
		xData, 		//!< pointer to a buffer with the x data
		yData, 		//!< pointer to a buffer with the y data
		zData);		//!< pointer to a buffer with the z data

Read the each column of data into the buffers.

	unsigned long size = 0;
	while((size = dataReader.read()) > 0)	//Each call to dataReader.read() will retrieve the next column of data.
	{
		for(unsigned long i = 0; i < size; i++)		//x,y,z Data buffers have the next column of data.
		{
			Point p(xData[i],yData[i],zData[i]);	//access each point in the row
		}
	}

Close the reader and clean up the buffer.

	dataReader.close();
	delete xData;
	delete yData;
	delete zData;

Writing using the E57 Simple API

Include required header files from the libE57 release.

	#include "E57Foundation.h"
	#include "E57Simple.h"

Instantiate an e57::Writer object that will create the .e57 file.

	e57::Writer 	eWriter("file.e57");

Setup an e57::Data3D header object with the information about the first scan.

	e57::Data3D	scanHeader;

	scanHeader.guid = "{D3817EC3-A3DD-4a81-9EF5-2FFD0EC91D5A}";
	...

Setup the size information about the scan data.

	scanHeader.pointsSize = (nColumn * nRow);

Setup the point record field information.

	scanHeader.pointFields.cartesianXField = true;
	scanHeader.pointFields.cartesianYField = true;
	scanHeader.pointFields.cartesianZField = true;

Write out a new scan header and receive back the index position.

	int scanIndex = eWriter.NewData3D(scanHeader);

Setup the buffers and setup the e57::CompressedVectorWriter point data object.

	int64_t nSize = nRow;				//Pick a size for buffers
	double *xData = new double[nSize];
	double *yData = new double[nSize];
	double *zData = new double[nSize];

	e57::CompressedVectorWriter dataWriter = eWriter.SetUpData3DPointsData(
		scanIndex, 	//!< scan data index 
		nSize, 		//!< size of each of the buffers given
		xData, 		//!< pointer to a buffer with the x data
		yData, 		//!< pointer to a buffer with the y data
		zData);		//!< pointer to a buffer with the z data

Insert a column of data into the buffers and write out.

	for(long col = 0; col < nColumn; col++)
	{
		for(long row = 0; row < nRow; row++)
		{
			Point p = GetPoint(row,col);//access each point in the column
			xData[row] = p.x();
			yData[row] = p.y();
			zData[row] = p.z();
		}
		dataWrite.write(nSize);	//write a column
	}

Close the writer and clean up the buffer.

	dataWriter.close();
	
	delete xData;
	delete yData;
	delete zData;

	eWriter.Close();		//important to close the file