Handle Various Control Network Versions. More...

#include <ControlNetVersioner.h>

Collaboration diagram for Isis::ControlNetVersioner:

Static Public Member Functions
static LatestControlNetFile *	Read (const FileName &file)
	Read the control network from disk.

static void	Write (const FileName &file, const LatestControlNetFile &, bool pvl=false)
	This will write a control net file object to disk.

Private Member Functions
	ControlNetVersioner ()
	The constructor is not implemented.

	ControlNetVersioner (const ControlNetVersioner &other)
	The constructor is not implemented so the copy constructor is impossible.

ControlNetVersioner &	operator= (const ControlNetVersioner &other)
	The constructor is not implemented so assignment is impossible.

Static Private Member Functions
static LatestControlNetFile *	ReadPvlNetwork (Pvl pvl)
	This interprets a Pvl network of any version.

static LatestControlNetFile *	LatestPvlToBinary (PvlObject &network)
	Convert a pvl (in the latest version) back to binary (LatestControlNetFile)

static LatestControlNetFile *	ReadBinaryNetwork (const Pvl &header, const FileName &file)
	This method is designed to read any and all binary networks.

static void	ConvertVersion1ToVersion2 (PvlObject &network)
	This converts pvl networks from their implied version 1 to version 2.

static void	ConvertVersion2ToVersion3 (PvlObject &network)
	This converts pvl networks from their version 2 to version 3.

static void	ConvertVersion3ToVersion4 (PvlObject &network)
	This converts pvl networks from their version 3 to version 4.

static void	Copy (PvlContainer &container, QString keyName, ControlPointFileEntryV0002 &point, void(ControlPointFileEntryV0002::*setter)(bool))
	This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002 for booleans.

static void	Copy (PvlContainer &container, QString keyName, ControlPointFileEntryV0002 &point, void(ControlPointFileEntryV0002::*setter)(double))
	This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002 for doubles.

static void	Copy (PvlContainer &container, QString keyName, ControlPointFileEntryV0002 &point, void(ControlPointFileEntryV0002::*setter)(const std::string &))
	This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002 for strings.

static void	Copy (PvlContainer &container, QString keyName, ControlPointFileEntryV0002::Measure &measure, void(ControlPointFileEntryV0002::Measure::*setter)(bool))
	This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002::Measure for booleans.

static void	Copy (PvlContainer &container, QString keyName, ControlPointFileEntryV0002::Measure &measure, void(ControlPointFileEntryV0002::Measure::*setter)(double))
	This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002::Measure for doubles.

static void	Copy (PvlContainer &container, QString keyName, ControlPointFileEntryV0002::Measure &measure, void(ControlPointFileEntryV0002::Measure::*setter)(const std::string &))
	This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002::Measure for strings.

Static Private Attributes
static const int	LATEST_PVL_VERSION = 4
	The latest version of the Pvl formatted control networks.

static const int	LATEST_BINARY_VERSION = 2
	The latest version of the Binary formatted control networks.

Detailed Description

Handle Various Control Network Versions.

This class is used to read any and all control networks.

All publicly released versions of binary control networks should be supported if possible.

                  ControlNetVersioner::Read
                 /                         \
             [If Pvl]                    [If Binary]
               /                             \
           Pvl::Read                         |
              |          [If not latest]     |
       Update To Latest <-- ToPvl --- ControlNetFileV????::Read
              |                              |  [If latest]
              |                              |
          Latest Pvl  ------------> Latest ControlNetFile
                                             |
                                             |
                                      Isis::ControlNet

We used to have the 4 conversions: Pvl -> Isis::ControlNet Binary -> Isis::ControlNet Pvl <- Isis::ControlNet Binary <- Isis::ControlNet

But maintaining these causes us to need the old ControlNet code around. These conversions are used instead: Pvl -> Binary *Latest version only Binary -> Pvl *All versions Binary -> Isis::ControlNet *Latest version only Binary <- Isis::ControlNet *Latest version only

The log data classes are still used to understand what log data is what, so these classes must remain backwards compatible. Otherwise all of the versioning code is here. I encourage the use of log data to avoid needing to make any changes in this code.

The reason the update cycle is only in Pvl form is because of how much simpler and less error-prone the code is to convert between versions in a generic file format. You don't need to do things like new.setNetworkId(old.getNetworkId()) in Pvl. Hopefully the speed cost is not significant enough to need an update cycle in binary form. It is a one-time cost per network, timed at about 5 minutes for our currently largest network (120MB protocol buffer file).

This class is the reason Isis::ControlNet only need to work with the latest version. Also, we only need 1-way conversions for old file formats (ControlNetFile::ToPvl).

If you want to change the Pvl format, you must update the following: Update LATEST_PVL_VERSION Write ConvertVersionAToVersionB Update ReadPvlNetwork Update LatestPvlToBinary

If you want to change the Binary format, you must update the following: Update LATEST_BINARY_VERSION Write ControlNetFileV???? Update ControlNetFile.h Update ReadBinaryNetwork Update LatestPvlToBinary

Author: 2011-04-05 Steven Lambright

History:

2011-04-14 Steven Lambright - Improved handling of V1 networks

2011-05-02 Tracie Sucharski - If Held=True exists in input net, set PointType=Ground.

2011-05-02 Debbie A. Cook - Created pvl version 3 which added point type of constrained.

2012-08-14 Steven Lambright - Simplified error handling of invalid target names in V1 networks (V1->V2 code).

2012-11-22 Debbie A. Cook - Changed to use TProjection instead of Projection. References #775.

2013-03-13 Steven Lambright and Stuart Sides - Added support for more V1 Pvl networks (specifically, isis3.2.1 hijitreg output networks with measures that lack Sample/Line and are set to unmeasured). Fixes #1554.

Definition at line 127 of file ControlNetVersioner.h.

Constructor & Destructor Documentation

Isis::ControlNetVersioner::ControlNetVersioner ( )

private

The constructor is not implemented.

Isis::ControlNetVersioner::ControlNetVersioner ( const ControlNetVersioner & other )

private

The constructor is not implemented so the copy constructor is impossible.

Parameters

other The versioner to copy from

Member Function Documentation

void Isis::ControlNetVersioner::ConvertVersion1ToVersion2 ( PvlObject & network )

staticprivate

This converts pvl networks from their implied version 1 to version 2.

We're trying to handle all cases of old keywords from over a very long time in this method, and end up with a consistent set of keywords so there is no more duplication or confusion about what will be in the Pvl.

Future conversions will have similar operations in them but will probably be smaller/less work.

Modify in place to prevent unnecessary memory usage.

Version 2 is the first version made inside this versioner. It is the first time keyword names and values cannot vary.

Parameters

network Input is Version 1, must be modified to conform to Version 2

Definition at line 461 of file ControlNetVersioner.cpp.

References _FILEINFO_, Isis::PvlContainer::addKeyword(), Isis::PvlContainer::deleteKeyword(), Isis::PvlObject::group(), Isis::PvlObject::groups(), Isis::PvlContainer::hasKeyword(), Isis::PvlObject::hasKeyword(), Isis::PvlContainer::keywords(), Isis::Displacement::meters(), Isis::PvlObject::object(), Isis::PvlObject::objects(), Isis::SurfacePoint::SetRadii(), Isis::SurfacePoint::SetRectangular(), Isis::SurfacePoint::SetSphericalSigmasDistance(), Isis::toDouble(), and Isis::toString().

void Isis::ControlNetVersioner::ConvertVersion2ToVersion3 ( PvlObject & network )

staticprivate

This converts pvl networks from their version 2 to version 3.

Modify in place to prevent unnecessary memory usage.

Parameters

network Input is Version 2, must be modified to conform to Version 3

Definition at line 752 of file ControlNetVersioner.cpp.

References Isis::PvlObject::hasKeyword(), Isis::PvlObject::object(), and Isis::PvlObject::objects().

void Isis::ControlNetVersioner::ConvertVersion3ToVersion4 ( PvlObject & network )

staticprivate

This converts pvl networks from their version 3 to version 4.

Modify in place to prevent unnecessary memory usage.

Parameters

network Input is Version 3, must be modified to conform to Version 4

Definition at line 773 of file ControlNetVersioner.cpp.

References Isis::PvlObject::object(), and Isis::PvlObject::objects().

void Isis::ControlNetVersioner::Copy	(	PvlContainer &	container,
		QString	keyName,
		ControlPointFileEntryV0002 &	point,
		void(ControlPointFileEntryV0002::*)(bool)	setter
	)

staticprivate

This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002 for booleans.

This operation is only necessary for the latest version of the binary so this method needs to be updated or removed when V0003 comes around.

If the keyword doesn't exist, this does nothing.

Parameters

container	The PvlObject that represents a control point
keyName	The keyword name inside the PvlObject
point	The protocol buffer point instance to set the value in
setter	The protocol buffer setter method

Definition at line 799 of file ControlNetVersioner.cpp.

References Isis::PvlContainer::deleteKeyword(), and Isis::PvlContainer::hasKeyword().

void Isis::ControlNetVersioner::Copy	(	PvlContainer &	container,
		QString	keyName,
		ControlPointFileEntryV0002 &	point,
		void(ControlPointFileEntryV0002::*)(double)	setter
	)

staticprivate

This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002 for doubles.

This operation is only necessary for the latest version of the binary so this method needs to be updated or removed when V0003 comes around.

If the keyword doesn't exist, this does nothing.

Parameters

container	The PvlObject that represents a control point
keyName	The keyword name inside the PvlObject
point	The protocol buffer point instance to set the value in
setter	The protocol buffer setter method

Definition at line 826 of file ControlNetVersioner.cpp.

References Isis::PvlContainer::deleteKeyword(), Isis::PvlContainer::hasKeyword(), and Isis::toDouble().

void Isis::ControlNetVersioner::Copy	(	PvlContainer &	container,
		QString	keyName,
		ControlPointFileEntryV0002 &	point,
		void(ControlPointFileEntryV0002::*)(const std::string &)	setter
	)

staticprivate

This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002 for strings.

This operation is only necessary for the latest version of the binary so this method needs to be updated or removed when V0003 comes around.

If the keyword doesn't exist, this does nothing.

Parameters

container	The PvlObject that represents a control point
keyName	The keyword name inside the PvlObject
point	The protocol buffer point instance to set the value in
setter	The protocol buffer setter method

Definition at line 851 of file ControlNetVersioner.cpp.

References Isis::PvlContainer::deleteKeyword(), and Isis::PvlContainer::hasKeyword().

void Isis::ControlNetVersioner::Copy	(	PvlContainer &	container,
		QString	keyName,
		ControlPointFileEntryV0002::Measure &	measure,
		void(ControlPointFileEntryV0002::Measure::*)(bool)	setter
	)

staticprivate

This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002::Measure for booleans.

This operation is only necessary for the latest version of the binary so this method needs to be updated or removed when V0003 comes around.

If the keyword doesn't exist, this does nothing.

Parameters

container	The PvlObject that represents a control point
keyName	The keyword name inside the PvlObject
measure	The protocol buffer point instance to set the value in
setter	The protocol buffer setter method

Definition at line 876 of file ControlNetVersioner.cpp.

References Isis::PvlContainer::deleteKeyword(), and Isis::PvlContainer::hasKeyword().

void Isis::ControlNetVersioner::Copy	(	PvlContainer &	container,
		QString	keyName,
		ControlPointFileEntryV0002::Measure &	measure,
		void(ControlPointFileEntryV0002::Measure::*)(double)	setter
	)

staticprivate

This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002::Measure for doubles.

This operation is only necessary for the latest version of the binary so this method needs to be updated or removed when V0003 comes around.

If the keyword doesn't exist, this does nothing.

Parameters

container	The PvlObject that represents a control point
keyName	The keyword name inside the PvlObject
measure	The protocol buffer point instance to set the value in
setter	The protocol buffer setter method

Definition at line 903 of file ControlNetVersioner.cpp.

References Isis::PvlContainer::deleteKeyword(), Isis::PvlContainer::hasKeyword(), and Isis::toDouble().

void Isis::ControlNetVersioner::Copy	(	PvlContainer &	container,
		QString	keyName,
		ControlPointFileEntryV0002::Measure &	measure,
		void(ControlPointFileEntryV0002::Measure::*)(const std::string &)	set
	)

staticprivate

This is a convenience method for copying keywords out of the container and into the ControlPointFileEntryV0002::Measure for strings.

This operation is only necessary for the latest version of the binary so this method needs to be updated or removed when V0003 comes around.

If the keyword doesn't exist, this does nothing.

Parameters

container	The PvlObject that represents a control point
keyName	The keyword name inside the PvlObject
measure	The protocol buffer point instance to set the value in
set	The protocol buffer setter method

Definition at line 928 of file ControlNetVersioner.cpp.

References Isis::PvlContainer::deleteKeyword(), and Isis::PvlContainer::hasKeyword().

LatestControlNetFile * Isis::ControlNetVersioner::LatestPvlToBinary ( PvlObject & network )

staticprivate

Convert a pvl (in the latest version) back to binary (LatestControlNetFile)

This does exactly what you think it would do - it copies PvlKeywords into protocol buffer objects. Helper methods Copy(...) do most of the work. Any unexpected keywords in the Pvl will cause an exception to be thrown. Not enough keywords in the Pvl will cause an exception to be thrown. The returned LatestControlNetFile is guaranteed to have all required fields.

Parameters

network The input PVL Control Network to convert

Definition at line 153 of file ControlNetVersioner.cpp.

References _FILEINFO_, Isis::PvlContainer::deleteKeyword(), Isis::PvlObject::findKeyword(), Isis::ControlNetFileV0002::GetNetworkHeader(), Isis::ControlNetFileV0002::GetNetworkPoints(), Isis::PvlContainer::hasKeyword(), Isis::ControlMeasureLogData::IsValid(), Isis::PvlContainer::keywords(), Isis::PvlContainer::name(), Isis::PvlObject::object(), Isis::PvlObject::objects(), Isis::toDouble(), and Isis::ControlMeasureLogData::ToProtocolBuffer().

ControlNetVersioner& Isis::ControlNetVersioner::operator= ( const ControlNetVersioner & other )

private

The constructor is not implemented so assignment is impossible.

Parameters

other The versioner to copy from

LatestControlNetFile * Isis::ControlNetVersioner::Read ( const FileName & networkFileName )

static

Read the control network from disk.

This will always return the network in its "latest version" binary form. Generally this will only be called by ControlNet but a conversion from binary to pvl can make use out of this also.

Parameters

networkFileName The filename of the cnet to be read

Definition at line 39 of file ControlNetVersioner.cpp.

References _FILEINFO_.

Referenced by Isis::ControlNetDiff::compare().

LatestControlNetFile * Isis::ControlNetVersioner::ReadBinaryNetwork	(	const Pvl &	header,
		const FileName &	filename
	)

staticprivate

This method is designed to read any and all binary networks.

Old versions will be sent to ReadPvlNetwork.

Parameters

header	The Pvl at the top of the binary file
filename	The file that contains the binary network

Returns: In-memory representation of the network

Definition at line 399 of file ControlNetVersioner.cpp.

References _FILEINFO_, Isis::PvlObject::findGroup(), Isis::PvlObject::findObject(), Isis::PvlContainer::hasKeyword(), Isis::ControlNetFile::Read(), Isis::toInt(), and Isis::ControlNetFile::toPvl().

LatestControlNetFile * Isis::ControlNetVersioner::ReadPvlNetwork ( Pvl pvl )

staticprivate

This interprets a Pvl network of any version.

Since we already have the Pvl in memory (we need it to figure out if it is a Pvl network) it does not actually call Pvl::Read.

The update cycle is contained in this method. Old versions of Pvl will be updated until they reach the latest version and then LatestPvlToBinary will be called to convert it back to a LatestControlNetFile.

To add a new version, you only need to add a case to the switch that calls a method (ConvertVersionAToVersionB). No other code should be necessary. ConvertVersionAToVersionB is expected to update the Pvl's version number.

Parameters

pvl	The pvl network obtained from Pvl::Read on the input filename

Definition at line 98 of file ControlNetVersioner.cpp.

References _FILEINFO_, Isis::PvlObject::findObject(), Isis::PvlObject::hasKeyword(), and Isis::toInt().

void Isis::ControlNetVersioner::Write	(	const FileName &	file,
		const LatestControlNetFile &	fileData,
		bool	pvl = `false`
	)

static

This will write a control net file object to disk.

Parameters

file	file The output filename that will be written to
fileData	The ControlNetFile representation to write
pvl	True if the output format should be Pvl, false if not

Definition at line 71 of file ControlNetVersioner.cpp.

References Isis::ControlNetFileV0002::toPvl(), Isis::ControlNetFileV0002::Write(), and Isis::Pvl::write().

Member Data Documentation

const int Isis::ControlNetVersioner::LATEST_BINARY_VERSION = 2

staticprivate

The latest version of the Binary formatted control networks.

Definition at line 150 of file ControlNetVersioner.h.

const int Isis::ControlNetVersioner::LATEST_PVL_VERSION = 4

staticprivate

The latest version of the Pvl formatted control networks.

Definition at line 148 of file ControlNetVersioner.h.

The documentation for this class was generated from the following files:

src/control/objs/ControlNetVersioner/ControlNetVersioner.h
src/control/objs/ControlNetVersioner/ControlNetVersioner.cpp

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation