Libcurvecollection: Difference between revisions
mNo edit summary |
No edit summary |
||
| Line 59: | Line 59: | ||
Looks up the given property name and returns a reference to the vertex property (in the current CurveVertex) that it identifies. Because the return value is a reference, you can modify the stored property value (assuming you called the non-<tt>const</tt> version of the function). | Looks up the given property name and returns a reference to the vertex property (in the current CurveVertex) that it identifies. Because the return value is a reference, you can modify the stored property value (assuming you called the non-<tt>const</tt> version of the function). | ||
Note that the Curve Collection | Note that the Curve Collection Library stores property names only at the highest level (i.e., in a CurveCollection). Therefore, the CurveVertex in question must be in a Curve, and that Curve must be in a CurveCollection before you can call this method. If you call it before this has happened, the program will exit with a <tt>runtime_error</tt> (''CurveVertex::checkForContainer: ...''). | ||
<ref>libcurvecollection uses exceptions built into the C++ Standard Library ([http://www.cplusplus.com/reference/std/stdexcept/ stdexcept]).</ref> | |||
If the lookup fails (i.e., the given string ''name'' was not found in the CurveCollection), the method will throw an <tt>invalid_argument</tt> exception. | If the lookup fails (i.e., the given string ''name'' was not found in the CurveCollection), the method will throw an <tt>invalid_argument</tt> exception. | ||
<code>double & property(int id)</code> | |||
<code>double const & property(int id) const</code> | |||
Returns a reference the vertex property identified by the ''Property ID''. Throws an <tt>invalid_argument</tt> exception if the given ID is out of bounds. | |||
<blockquote>''What is a Property ID?'' <br /> | |||
A Property ID is essentially the index of the position in the vector where a property is stored. You can look it up using the <tt>CurveCollection::getVertexPropertyID</tt> method. | |||
<br /><br /> | |||
''Why use a Property ID?'' <br /> | |||
As the library explains, "those wishing to call getProperty from within a loop may want to avoid | |||
the efficiency loss associated with looking up the name at each call. | |||
Instead, they can perform the lookup once using | |||
<tt>curveCollection::getVertexPropertyID</tt>, and pass the resulting int ID | |||
to getProperty inside their loop."</blockquote> | |||
Revision as of 21:47, 18 June 2010
The Curve Collection Library (libcurvecollection) provides a representation of streamlines/curves in memory and an interface to access this information in a convenient but memory-safe manner. It can also read and write to disk, freely converting between several file formats.
Currently, the supported formats are:
- DTK/TrackVis
- Tubegen's custom format (.data and .nocr files)
- CCF
Introduction
Tubegen represents streamlines/tubes in several different formats in memory and on disk, which are distinct from the representations used by well-established third parties, for example FSL, Camino, and DTK. The core of any representation, though, is quite simple: a collection of streamlines, in which each streamline is just an ordered list of vertex points in 3-space. The tricky bit is that we want to be able to associate scalars with these datasets at various levels:
- each individual streamline (ex: the length of the streamline)
- each vertex point of each streamline (ex: the interpolated FA value at that point)
Some of the data formats also include a description (i.e., a string) for each scalar value.
libcurvecollection provides a unified interface for handling these various formats, while simplifying access to the information in memory by presenting it in a object-oriented fashion.
Installation
The Curve Collection library can be found under $G/common/libcurvecollection/. To install it, run make clean all, then make install. ???
To use the library after it has been installed, include the line #include <brain/curveCollection.h near the top of your file.
Structure
The library consists of three mutually dependent components, each with a header (.h) and a .cpp file:
CurveVertex
A CurveVertex represents a point in 3D space. It holds the point's coordinates and any metadata (in the form of doubles) that the point may have.
Constructors
CurveVertex(double, double, double)
The main constructor takes three doubles: the x, y, and z coordinates of the point.
CurveVertex(CurveVertex const & v)
A vertex instantiated using a copy constructor will have the same coordinates and properties as the source, but will not belong to any Curve. Thus, the properties can only be accessed by calling property(int) (and not property(string)).
Accessors
double x() const
double y() const
double z() const
Property accessors & mutators
double & property(std::string const & name)
double const & property(std::string const & name) const
Looks up the given property name and returns a reference to the vertex property (in the current CurveVertex) that it identifies. Because the return value is a reference, you can modify the stored property value (assuming you called the non-const version of the function).
Note that the Curve Collection Library stores property names only at the highest level (i.e., in a CurveCollection). Therefore, the CurveVertex in question must be in a Curve, and that Curve must be in a CurveCollection before you can call this method. If you call it before this has happened, the program will exit with a runtime_error (CurveVertex::checkForContainer: ...). [1]
If the lookup fails (i.e., the given string name was not found in the CurveCollection), the method will throw an invalid_argument exception.
double & property(int id)
double const & property(int id) const
Returns a reference the vertex property identified by the Property ID. Throws an invalid_argument exception if the given ID is out of bounds.
What is a Property ID?
A Property ID is essentially the index of the position in the vector where a property is stored. You can look it up using the CurveCollection::getVertexPropertyID method.
Why use a Property ID?
As the library explains, "those wishing to call getProperty from within a loop may want to avoid the efficiency loss associated with looking up the name at each call. Instead, they can perform the lookup once using curveCollection::getVertexPropertyID, and pass the resulting int IDto getProperty inside their loop."