Extension Name

	E57_SP1_Index_Limits
	
XML namespace

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

Contact

	Stan Coleby, Intelisum (scoleby @ intelisum.com)	
	Stan Coleby, Cerisoft LLC (stan . coleby @ gmail.com)

Contributors

	none.
	
Version

	Last Modified Date: September 30, 2011
		Revision: 1

Dependencies

	none.
 
Overview

	This extension adds the IndexLimits structure to the data3D structure.
	When the standard defined the IndexBounds structure the standard states that the
	bounds are defined to be tight to the data given. The standard defines rowMaximum
	to be "The maximum rowIndex value of any point represented by this IndexBounds
	object."  The problem with this is that it doesn't meet the real world need to
	know the index limits for structured point clouds. In order to know all the
	invalid points that occurred outside the indexBounds mim/max bounds, we need
	to know what the index limits were when it was scanned.
	
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
		
	"sp1:indexLimits"		Structure				The original grid size scan data
													index limits structure
	
	"sp1:rowMinimum"		Integer					The minimum rowIndex value
	"sp1:rowMaximum"		Integer					The maximum rowIndex value
	"sp1:columnMinimum"		Integer					The minimum columnIndex value
	"sp1:columnMaximum"		Integer					The maximum columnIndex value
	"sp1:returnMinimum"		Integer					The minimum returnIndex value
	"sp1:returnMaximum"		Integer					The maximum returnIndex value
			
XML Example

<data3D type="Vector" allowHeterogeneousChildren="1">
    <vectorChild type="Structure">
	...
		<sp1:indexLimits type="Structure">
			<sp1:rowMinimum type="Integer"/>
			<sp1:rowMaximum type="Integer">543</rowMaximum>
			<sp1:columnMinimum type="Integer"/>
			<sp1:columnMaximum type="Integer">2473</columnMaximum>
			<sp1:returnMinimum type="Integer"/>
			<sp1:returnMaximum type="Integer">1</returnMaximum>
		</sp1:indexLimits>
	...
     </vectorChild>
  </data3D>

Sample Code

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

//Given scan grid size

	int nSizeRow = ..;			//scan total rows
	int nSizeColumns = ..;		//scan total columns
	int nSizeReturns = ..;		//scan total returns
	int 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	indexLimits = StructureNode(imf_);
	indexLimits.set("sp1:rowMinimum", IntegerNode(imf_, 0 ));
	indexLimits.set("sp1:rowMaximum", IntegerNode(imf_, nSizeRows - 1));
	indexLimits.set("sp1:columnMinimum", IntegerNode(imf_, 0 ));
	indexLimits.set("sp1:columnMaximum", IntegerNode(imf_, nSizeColumns - 1));
	indexLimits.set("sp1:returnMinimum", IntegerNode(imf_, 0 ));
	indexLimits.set("sp1:returnMaximum", IntegerNode(imf_, nSizeReturns - 1));
	scan.set("sp1:indexLimits", indexLimits);
	
///////////////////////////
//Read scan grid bounds
/////////////////////////	

// 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));

	double	rowMaximum = 0.;
	double  rowMinimum = 0.;
	double	columnMaximum = 0.;
	double	columnMinimum = 0.;
	double	returnMaximum = 0.;
	double	returnMinimum = 0.;
	if(scan.isDefined("sp1:indexLimits"))
	{
		StructureNode xbox(scan.get("sp1:indexLimitss"));
		if(xbox.isDefined("sp1:rowMaximum"))
		{
			rowMinimum = IntegerNode(xbox.get("sp1:rowMinimum")).value();
			rowMaximum = IntegerNode(xbox.get("sp1:rowMaximum")).value();
		}
		if(xbox.isDefined("sp1:columnMaximum"))
		{
			columnMinimum = IntegerNode(xbox.get("sp1:columnMinimum")).value();
			columnMaximum = IntegerNode(xbox.get("sp1:columnMaximum")).value();
		}
		if(xbox.isDefined("sp1:returnMaximum"))
		{
			returnMinimum = IntegerNode(xbox.get("sp1:returnMinimum")).value();
			returnMaximum = IntegerNode(xbox.get("sp1:returnMaximum")).value();
		}
	}
	else if(scan.isDefined("indexBounds"))
	{
		StructureNode ibox(scan.get("indexBounds"));
		if(ibox.isDefined("rowMaximum"))
		{
			rowMinimum = IntegerNode(ibox.get("rowMinimum")).value();
			rowMaximum = IntegerNode(ibox.get("rowMaximum")).value();
		}
		if(ibox.isDefined("columnMaximum"))
		{
			columnMinimum = IntegerNode(ibox.get("columnMinimum")).value();
			columnMaximum = IntegerNode(ibox.get("columnMaximum")).value();
		}
		if(ibox.isDefined("returnMaximum"))
		{
			returnMinimum = IntegerNode(ibox.get("returnMinimum")).value();
			returnMaximum = IntegerNode(ibox.get("returnMaximum")).value();
		}
	}
	long	nSizeRows = rowMaximum - rowMinimum + 1;
	long	nSizeColumns = columnMaximum - columnMinimum + 1;
	long	nSizeReturns = returnMaximum - returnMinimum + 1;
	
Issues

	none

ASTM E57 Listed

	Submitted Date: September 30, 2011

Revision History

	Revision 1, 2011/09/30
	- Initial version of this document

Copyright

	Copyright (c) 2010 Stan Coleby (scoleby @ intelisum.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.