Extension Name

	E57_LEICA_Time_Bounds
	
XML namespace

	DIST		xmlns:time="http://www.libe57.org/E57_LEICA_Time_Bounds.txt"

Contact

	Aldo Facchin, Leica GeoSystems (aldo . facchin @ leica-geosystems.com)
	Stan Coleby, Cerisoft LLC (stan . coleby @ gmail.com)

Contributors

	none.
	
Version

	Last Modified Date: October 5, 2014
		Revision: 1

Dependencies

	none.
 
Overview

	This extension adds a higher precision of time bounds to the data3D structure.
	The E57 standard defines the timestamp data relative to the GPS acquisitionStart field.
	The problem with using the full GPS time is that it is only accurate to about 1 ms.  The common
	practice is to only use the GPS week time without the GPS week number number mixed in order to give
	a better resolution down to .1 us.  This extension gives the minimum and maximum value of the
	timestamp data in GPS week time	using the same accuracy as found in the point cloud timestamp data.
	
IP Status

	No known IP claims.

New <E57Root> Fields

	none.

New PointRecord Fields

	none.
	
New <images2D> Fields

	none.
	
New <data3D> Fields	

	Element Name			Type						Description
		
	"time:timeBounds"		Structure				Point data timestamp bound structure
	
	"time:timeMaximum"		Float					This is the highest value found in the timestamp in GPS week time seconds
	"time:timeMinimum"		Float					This is the lower value found in the timestamp in GPS week time seconds
	
	The point cloud timestamp is the time(in seconds) since the start time for the data, which
	is given by acquisitionStart in the parent Data3D Structure.  This extension changes this
	to use the timeMinimum instead of the acquisitionStart. 
	
		double T = point.TimeStamp + timeMinimum;  // to get T in GPSWeekTime with .1 us resolution.
		
		or
		
		double gps_week_number = ((int)floor(acquisitionStart))/604800;
		double T = point.TimeStamp + timeMinimum + gps_week_number*604800; //full GPS time with lost of resolution.
			
XML Example

<data3D type="Vector" allowHeterogeneousChildren="1">
    <vectorChild type="Structure">
	...
		<time:timeBounds type="Structure">
			<time:timeMaximum type="Float">1.9706593919999999e+005</time:timeMaximum>
			<time:timeMinimum type="Float">1.9705106339999998e+005</time:timeMinimum>
		</time:timeBounds>
	...
     </vectorChild>
  </data3D>

Sample Code

//////////////////////////////////
// Writing Extension declaration//
//////////////////////////////////
// FoundationAPI
	_imf.extensionsAdd("time","http://www.libe57.org/E57_DIST_Time_Bounds.txt");
	...
// Sample API
	e57::Writer pWriter(...);
	pWriter.GetRawIMF().extensionsAdd("time","http://www.libe57.org/E57_DIST_Time_Bounds.txt");
	
///////////////////////////////	
// Write time bounds
//////////////////////////////

//Given good distortion data

	double timeMin = ..;		//start in GPS week time
	double timeMax = ..;		//end in GPS week time
	integer scanIndex = ..;  Get the scan index
	...
	
// Sample API	
	ImageFile	_imf = pWriter.GetRawIMF();
	VectorNode	_data3D = pWriter.GetRawData3D();
	if( (scanIndex < 0) || (scanIndex >= _data3D.childCount()))
		return false;

// Both API
		
	//access the data3D structure
	StructureNode scan(_data3D.get(scanIndex));

	StructureNode timeBounds = StructureNode(_imf);
	timeBounds.set("time:timeMaximum", FloatNode(_imf,timeMax));
	timeBounds.set("time:timeMinimum", FloatNode(_imf,timeMin));
	scan.set("time:timeBounds", timeBounds);

// When writing the point's timeStamp data substract this timeMin
	
	timeStamp = t - timeMin;
	
///////////////////////////
//Read time bounds data
/////////////////////////	

// Sample API	
	e57::Reader pReader(....);
	...
	VectorNode	_data3D = pReader.GetRawData3D();
	if( (scanIndex < 0) || (scanIndex >= _data3D.childCount()))
		return false;
		
// Both API

//access the data3D structure
	StructureNode scan(_data3D.get(scanIndex));

	ustring url;
	if (pReader.GetRawIMF().extensionsLookupPrefix("time", url))
	{
		if(scan.isDefined("time:timeBounds"))
		{
			StructureNode timeBounds(scan.get("time:timeBounds"));

			if(timeBounds.isDefined("time:timeMaximum"))
				timeMax = FloatNode(timeBounds.get("time:timeMaximum")).value();
			if(timeBounds.isDefined("time:timeMinimum"))
				timeMin = FloatNode(timeBounds.get("time:timeMinimum")).value();
			return true;
		}
	}
	
// When reading the point's timeStamp data add this timeMin
	
	t = timeStamp + timeMin;
	
Issues

	none

ASTM E57 Listed

	Submitted Date: November 12, 2014

Revision History

	Revision 1, 2014/10/05
	- Initial version of this document

Copyright

	Copyright (c) 2014 Aldo Facchin Leica GeoSystems(aldo . facchin @ leica-geosystems.com), All Rights Reserved.

	Permission is hereby granted, free of charge, to any person or organization obtaining a copy of this extension 
	and accompanying documentation covered by this license (this "Extension") to use, reproduce, display, distribute, 
	execute, and transmit this Extension, and to prepare derivative works of this Extension, and to permit third-parties 
	to whom this Extension is furnished to do so, all subject to the following:

	The copyright notices in this Extension and this entire statement, including the above license grant, this restriction 
	and the following disclaimer, must be included in all copies of this Extension, in whole or in part, and all derivative 
	works of this Extension, unless such copies or derivative works are solely in the form of machine-executable object code 
	generated by a source language processor.

Disclaimer

	THIS EXTENSION IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
	THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL 
	THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THIS EXTENSION BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN 
	CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THIS EXTENSION OR THE USE OR OTHER DEALINGS 
	IN THIS EXTENSION.