Isis::ControlNetVersioner Class Reference

Handle various control network file format versions. More...

#include <ControlNetVersioner.h>

Collaboration diagram for Isis::ControlNetVersioner:

Public Member Functions
	ControlNetVersioner (ControlNet *net)
	Construct a ControlNetVersioner from a control network.
	ControlNetVersioner (const FileName netFile, Progress *progress=NULL)
	Construct a ControlNetVersioner from a file.
	~ControlNetVersioner ()
	Destroy a ControlNetVersioner.
QString	netId () const
	Returns the ID for the network.
QString	targetName () const
	Returns the target for the network.
QString	creationDate () const
	Returns the date and time that the network was created.
QString	lastModificationDate () const
	Returns the date and time of the last modification to the network.
QString	description () const
	Returns the network's description.
QString	userName () const
	Returns the name of the last person or program to modify the network.
int	numPoints () const
	Returns the number of points that have been read in or are ready to write out.
ControlPoint *	takeFirstPoint ()
	Returns the first point stored in the versioner's internal list.
void	write (FileName netFile)
	This will write a control net file object to disk.
Pvl	toPvl ()
	Generates a Pvl file from the currently stored control points and header.

Detailed Description

Handle various control network file format versions.

Overview

This class is used to read all versions of control networks and write out the most recent version in Pvl and protobuf format. When reading a control net file, the ControlNeVersioner is initialized with the filename. When writing a control net file or generating a Pvl network, the ControlNetVersioner is initialized from a ControlNet object.

This class exists to isolate the code dealing with control network file formats. ControlNet can then interface with this class and only has to work with the current ControlPoint object.

Reading Control Network Files

The read routine is as follows:

1. Read the Pvl file header
2. Determine if the network is stored in Pvl or protobuf format
3. Determine the version of the network
4. Read in the general ControlNet information such as network description, last modification date, etc. For Pvl networks, this information is in a PvlObject at the start of the network. For protobuf objects this information is stored in a header protobuf message after the Pvl file header.
5. For each control point do the following:
   1. Read the control point into the appropriate ControlPointV#### object.
   2. If the ControlPointV#### object is not the most recent version, upgrade it to the latest version.
   3. Convert the final ControlPointV#### object into a ControlPoint object and store it in the ControlNetVersioner.

Once the ControlNet file is read into the ControlNetVersioner, the ControlPoints can be accessed through the takeFirstPoint method. This will remove the first ControlPoint stored in the ControlNetVersioner and give it to the caller. At this point, the caller is given ownership of the ControlPoint and is expected to delete it when finished. General information about the control network can be accessed directly from the ControlNetVersioner.

Writing Control Network Files

The protobuf file write routine is as follows:

1. Copy the general ControlNet information such as network description, last modification date, etc. into the ControlNetVersioner.
2. Copy the pointers to the ControlPoints and store them in the ControlNetVersioner. The ControlNetVersioner does not assume ownership of the ControlPoints when it does this. The ControlNet or what the ControlNet got the points from retains ownership.
3. Write a 65536 byte blank header to the file.
4. Write the general ControlNet information to a protobuf message header after the blank header.
5. For each control point do the following:
   1. Convert the control point into a protobuf message.
   2. Write the size of the protobuf message to the file.
   3. Write the protobuf message to the file.
6. Write a Pvl header into the original blank header at the start of the file. This header contains: a flag indicating the network is a protobuf formatted network, the version of the format, the byte offset and size of the protobuf header, the byte offset and size of the block of protobuf control points, and general information about the control network.

Once the ControlNetVersioner is initialized from a file or a ControlNet, a Pvl formatted version of the control network can be created by the toPvl method. This will always output the control network in the latest Pvl format. From here, the Pvl network can be written to a file with Pvl::write(filename).

Modifying the Control Network File Format

If the control network file format is changed the following changes need to be made to ControlNetVersioner and its supporting classes:

• New containers need to be added to interface with the new format. These containers should try to match the format of the data in the file, then the versioner will convert from that format to ControlNet, ControlPoint, ControlMeasure, and ControlMeasureLogData. General information about the control network should be stored in the ControlNetHeaderV#### structs. Data for control points should be stored in ControlPointV#### objects.
• If a new control point container was created, code needs to be added to create ControlPoint objects from them. A new createPoint method that takes the new container should be added to do this. The createMeasure method should also be changed to create ControlMeasures from the new containers.
• If a new header container was created, code needs to be added to store its information in the ControlNetVersioner. A new createHeader method that takes the new header container should be added to do this.
• New code needs to be added to update the previous containers to the new containers. Updating control point containers should happen in the new ControlPointV#### container class. It should have a constructor that takes a container for the previous version. Then, the createPoint method for the previous version needs to be changed to create a new container with this and then call the createPoint method for the new version. Updating header containers should happen in the createHeader method that takes the previous version. If the headers become more complicated, this may need to change to match how control point containers are updated.
• New methods need to be added to read the new file format. Methods for reading Pvl formatted files and protobuf formatted files need to be added; they should match the naming convention of readPvlV#### and readProtobufV#### respectively.
• New methods need to be added to write out the new file format. The write method should be changed to write out the new protobuf format. If a new header container is added, the writeHeader method should be changed to write the new protobuf header to the file. If a new control point container is added, the writeFirstPoint method should be changed to write a new protobuf control point to the file.
• Update the documentation on this class under the Control Network File Format History heading. This should include a description of the new file format and how it differs from the previous version.

Control Network File Format History

Prior to the creation of this versioning class, which was released with ISIS 3.2.2, all control network files were Pvl formatted text files. Reading and writing these files was handled by the ControlNet, ControlPoint, and ControlMeasure classes. As the file format was changed, those classes were modified to account for the new format. Because of this, the history of the control network file format prior to ISIS 3.2.2 is not well documented.

The following are descriptions of the different control network file format versions that are currently supported. Each description also describes how that version differs from the previous.

Version 1

This version maintains backwards compatibility with all files created prior to versioning. If a control network file does not have a version flag, then it is assumed to be a version 1 file. Because this version supports all files created prior to ISIS 3.2.2, there is no standardized Pvl format associated with it.

Originally, there was no version 1 binary format. When version 2 was added, version 1 was changed to use the version 2 binary format.

Version 2

This version was the first to have a standardized format. The following were standardized with this format:

• The Held flag was replaced by point types. Points could be either Tie points or Ground points. Points that were previously flagged as Held were changed to Ground points.
• A posteriori was replaced with adjusted in several keyword names.
• The a priori and adjusted ground points were changed from (latitude, longitude, radius) format to body fixed (X, Y, Z) format.
• Ground point sigmas were replaced with covariance matrices.
• Latitude, longitude, and radius constrained flags were added.
• Estimated measures were renamed to Candidate measures.
• Unmeasured measures were renamed to Candidate measures, had their line and sample set to 0, and were flagged as ignored.
• Automatic, ValidatedManual and AutomaticPixel measures were renamed to RegisteredPixel measures.
• ValidatedAutomatic and AutomaticSubPixel measures were renamed to RegisteredSubPixel measures.
• ErrorSample and ErrorLine were renamed to SampleResidual and LineResidual respectively.
• Diameter, ZScore, and ErrorMagnitude were no longer saved in measures.

Version 2 was the first version to support a binary protobuf format. Version 1 was retroactively changed to use the version 2 binary format. Version 2 binary control network files consist of three parts:

1. Pvl File Header: The file starts with a Pvl formatted header that contains offsets to the binary components of the file and the version number of the file. This header may also contain general information about the control network that is only for user reference is not used when reading the file.
2. Protobuf Core: After the Pvl header is the protobuf core that contains the majority of the network data. This is a hierarchical structure with general network information such as the network description at the top level. Below that is the control point information. The lowest level contains the control measure information. This structure is defined by ControlNetFileProtoV0001.proto.
3. Protobuf Log Data: The final component of the file contains the control measure log data. This is structured the same as the protobuf core. So, the log data for the i^th measure in the j^th point in the core is in the i^th measure of the j^th point in this structure. This structure is defined by ControlNetLogDataProtoV0001.proto.

Version 3

This version was created to avoid file size limits imposed by the version 2 binary file format. Protobuf messages are limited to 2GB for security reasons. So, version 2 binary files can only contain 2GB of information in their Protobuf Core. In version 3, the Protobuf Core was changed from a single message to a header message and individual messages for each control point. This way, the Protobuf Core could contain an arbitrary amount of information as long as any single point does not exceed 2GB. At the same time, control measure log data was moved into the Protobuf Core so that each measure contains its own log data.

Version 3 binary control network files are formatted as follows:

• pvl File Header: The Pvl Header in version 3 binary files is the same as the Pvl Header in version 2 binary files, except it has offsets to the Protobuf Header and Protobuf Core instead of the Protobuf Core and Protobuf Log Data.
• Protobuf Header: The binary component of version 3 binary control network files starts with a protobuf message header that contains general information about the network and the size of each control point's protobuf message. The size of each control point message is required to parse the Protobuf Core because protobuf messages are not self-delimiting. This structure is defined by ControlNetFileHeaderV0002.proto.
• Protobuf Core: Immediately after the Protobuf Header is the Protobuf Core which contains all of the control point and control measure information. This is structured as consecutive protobuf messages where each message contains all of the information for a control point and its control measures. Because protobuf messages are not self-delimiting, the size of each message must be known prior to parsing the Protobuf Core. The control point messages are defined by ControlPointFileEntryV0002.proto.

Version 3 also further differentiated control point types. Control points that had their latitude, longitude, and/or radius constrained were changed from Tie points to Constrained points.

Version 4

This version was created when Ground and Tie control points were renamed to Fixed and Free respectively. Version 4 Pvl control network files are identical to version 3 Pvl control network files, except for the new control point type values. When version 4 was created, the .proto file that defined control point protobuf messages was modified to allow for the new control point type names and the old names were flagged as deprecated. So, version 3 and version 4 binary control network files are formatted exactly the same.

Version 5

This version was created to allow for progressive reading and writing of binary control network files. Previous versions required the entire contents of binary control network files to be read into memory before the ControlNet, ControlPoint, and ControlMeasure objects could be created. Version 5 was created to allow binary control network files to be read one control point at a time. Similarly, previous versions required all of the information in the control network to be copied into protobuf structures before any of it could be written to a file.

Version 5 Pvl control network files are identical to version 4 Pvl control network files.

Version 5 binary control network files are formatted the same as version 4 binary control network files except for how they store the sizes of the control point messages in the Protobuf Core. In a version 5 binary control network file, each control point message is prepended by an unsigned, 32 bit, LSB, integer (c++ uint32_t) that contains the size of the message. This design was modeled after the delimited read and write functionality in the Java protobuf library. Additionally, the Protobuf Header contains the number of control points in the network instead of a list of all the control point message sizes. The structure of the Protobuf Header is defined by ControlNetFileHeaderV0005.proto. The structure of the protobuf messages in the Protobuf Core is defined by ControlPointFileEntryV0002.proto, the same as in version 4.

Starting with version 5, the naming scheme for .proto files was changed to use the same version number as the control net file format. So, the new .proto file defining the Protobuf Header was named ControlNetFileHeaderV0005.proto instead of ControlNetFileHeaderV0003.proto.

Author

2011-04-05 Steven Lambright

Constructor & Destructor Documentation

ControlNetVersioner() [1/2]

Isis::ControlNetVersioner::ControlNetVersioner

(

ControlNet *

net

)

Construct a ControlNetVersioner from a control network.

This versioner can only be used to write out the control points in the control network. It is expected that the control points in the control network will not be deleted while the control net versioner persists.

Parameters

net	A pointer to the network that will be written out.

ControlNetVersioner() [2/2]

Isis::ControlNetVersioner::ControlNetVersioner	(	const FileName	netFile,
		Progress *	progress = NULL )

Construct a ControlNetVersioner from a file.

The file will be read in and converted into a header object that contains general information about the network and a list of ControlPoints.

Parameters

netFile	The control network file to read in.
progress	The progress object to track reading points.

See also

ControlNetVersioner::Read

~ControlNetVersioner()

Isis::ControlNetVersioner::~ControlNetVersioner

(

)

Destroy a ControlNetVersioner.

If the versioner owns the control points stored in it, they will also be deleted.

Member Function Documentation

creationDate()

QString Isis::ControlNetVersioner::creationDate

(

)

const

Returns the date and time that the network was created.

Returns

QString The date and time the network was created as a string

description()

QString Isis::ControlNetVersioner::description

(

)

const

Returns the network's description.

Returns

QString A description of the network.

lastModificationDate()

QString Isis::ControlNetVersioner::lastModificationDate

(

)

const

Returns the date and time of the last modification to the network.

Returns

QString The date and time of the last modfication as a string

netId()

QString Isis::ControlNetVersioner::netId

(

)

const

Returns the ID for the network.

Returns

QString The network ID as a string

numPoints()

int Isis::ControlNetVersioner::numPoints

(

)

const

Returns the number of points that have been read in or are ready to write out.

Returns

int The number of control points stored internally.

Referenced by write().

takeFirstPoint()

ControlPoint * Isis::ControlNetVersioner::takeFirstPoint

(

)

Returns the first point stored in the versioner's internal list.

This method passes ownership of the point to the caller who is expected to delete it when done with it.

Returns

ControlPoint* A pointer to the control point. The caller assumes ownership of the ControlPoint and is expected to delete it when done. If there are no points to return, a NULL pointer is returned.

targetName()

QString Isis::ControlNetVersioner::targetName

(

)

const

Returns the target for the network.

Returns

QString The target name as a string

toPvl()

Pvl Isis::ControlNetVersioner::toPvl

(

)

Generates a Pvl file from the currently stored control points and header.

Returns

Pvl The Pvl version of the network

References _FILEINFO_, Isis::PvlKeyword::addComment(), Isis::PvlObject::addObject(), Isis::ControlPoint::SurfacePointSource::AverageOfMeasures, Isis::ControlPoint::RadiusSource::AverageOfMeasures, Isis::ControlPoint::SurfacePointSource::Basemap, Isis::ControlPoint::SurfacePointSource::BundleSolution, Isis::ControlPoint::RadiusSource::BundleSolution, Isis::ControlMeasure::Candidate, Isis::ControlPoint::Constrained, Isis::Angle::degrees(), Isis::ControlPoint::RadiusSource::DEM, Isis::ControlPoint::RadiusSource::Ellipsoid, Isis::PvlObject::findObject(), Isis::ControlPoint::Fixed, Isis::ControlPoint::GetAdjustedSurfacePoint(), Isis::ControlPoint::GetAprioriRadiusSource(), Isis::ControlPoint::GetAprioriRadiusSourceFile(), Isis::ControlPoint::GetAprioriSurfacePoint(), Isis::ControlPoint::GetAprioriSurfacePointSource(), Isis::ControlPoint::GetAprioriSurfacePointSourceFile(), Isis::ControlPoint::GetChooserName(), Isis::ControlPoint::GetDateTime(), Isis::ControlPoint::GetId(), Isis::SurfacePoint::GetLatitude(), Isis::SurfacePoint::GetLatSigmaDistance(), Isis::SurfacePoint::GetLocalRadius(), Isis::SurfacePoint::GetLocalRadiusSigma(), Isis::SurfacePoint::GetLongitude(), Isis::SurfacePoint::GetLonSigmaDistance(), Isis::ControlPoint::GetMeasure(), Isis::ControlPoint::GetNumMeasures(), Isis::SurfacePoint::GetRectangularMatrix(), Isis::ControlPoint::GetType(), Isis::SurfacePoint::GetX(), Isis::SurfacePoint::GetY(), Isis::SurfacePoint::GetZ(), Isis::ControlPoint::HasAprioriRadiusSourceFile(), Isis::ControlPoint::HasAprioriSurfacePointSourceFile(), Isis::ControlPoint::HasRefMeasure(), Isis::ControlPoint::IndexOfRefMeasure(), Isis::ControlPoint::IsCoord1Constrained(), Isis::ControlPoint::IsCoord2Constrained(), Isis::ControlPoint::IsEditLocked(), Isis::ControlPoint::IsIgnored(), Isis::ControlPoint::IsReferenceExplicit(), Isis::ControlMeasure::Manual, Isis::Displacement::meters(), Isis::Distance::meters(), Isis::ControlPoint::SurfacePointSource::None, Isis::ControlPoint::RadiusSource::None, Isis::Null, Isis::ControlPoint::SurfacePointSource::Reference, Isis::ControlMeasure::RegisteredPixel, Isis::ControlMeasure::RegisteredSubPixel, Isis::toString(), Isis::IException::Unknown, Isis::ControlPoint::SurfacePointSource::User, Isis::ControlPoint::RadiusSource::User, and Isis::SurfacePoint::Valid().

userName()

QString Isis::ControlNetVersioner::userName

(

)

const

Returns the name of the last person or program to modify the network.

Returns

QString The name of the last person or program to modify the network.

write()

void Isis::ControlNetVersioner::write

(

FileName

netFile

)

This will write a control net file object to disk.

Parameters

netFile

The output filename that will be written to

References _FILEINFO_, Isis::ControlPoint::GetNumMeasures(), Isis::IException::Io, numPoints(), and Isis::toString().

---

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

• /Users/chkim/repos/ISIS3/isis/src/control/objs/ControlNetVersioner/ControlNetVersioner.h
• /Users/chkim/repos/ISIS3/isis/src/control/objs/ControlNetVersioner/ControlNetVersioner.cpp