Formatting Guidelines
|
APPEARANCE
|
|
|
This page describes how to maintain the formatting of comments in the
automatically generated documentation.
|
Improving Appearance
To maintain the original formatting of comments included in a header file
(ie improve the appearance), you simply use HTML tags in your header file.
Example
To emphasise the effects of just adding a few tags, here is an example of what
the description in a header file looks like when viewed in netscape,
without and with tags.
No Tags |
-------------------------------------------------------------------------
********** BaseRangeC *************************************************
-------------------------------------------------------------------------
BaseRangeC is a virtual abstract base class from which ByteRangeC,
FloatRangeC and VectRangeC will be inherited.
The i/o routines do have basic error checks.
A valid image point is one in which a range measurement is available.
How it is stored is dependent on the data structure but can be checked
by calling the function IsValid(). In byte format, 0 is invalid and
in vector format, z=-MAXFLOAT is invalid.
Range data is much more complicated than image data. It can be
sampled on a regular grid or not, the grid spacings may vary.
Together ByteRangeC, FloatRangeC and VectRangeC provide a powerful
set of functionality. For accurate results it is important to understand
precisely how the system is set up.
Firstly we explain the conventions for "gridded data". Consider a
4 pixel image row or column.
--- <-- 0.0 xgridmin=0.0
| ____ box center = 0.5
|
___ <-- 1.0
|
|
___ <-- 2.0
|
|
___ <-- 3.0 xgridmax=3.0
|
|
___ <-- 4.0
There are nrows=4 rows, i.e. r=0..3=nrows-1. Each bin hase size 1
and the total range is 0.0 - 3.9999999.
For gridded data the pixels are deemed to be in the centers of the boxes,
i.e. at 0.5, 1.5, 2.5, 3.5.
With each range image, the minimum and maximum x, y and z values are
stored. In each case, the values are obtained by scanning all of the
valid image points and finding the extremes in each dimension. These
values are kept in xmin,xmax,ymin,ymax,zmin,zmax.
For conversions between row and column and x and y we use
gridxmin,gridxmax,gridymin,gridymax. They are defined as shown above in the
picture. In this example
For gridded data the xgridmin=0.0 xgridmax=3.0,
xmin=0.5 xmax=3.5
asuming valid pixels in the border rows.
These values are obtained if possible from the data file.
To summarize the conversion is as follows:
gridsize.X = (gridmax.X - gridmin.X) / (ncols-1)
PixelC OfVect(const Vector3dC vect) const
{
return PixelC (int(floor((vect.Y()-gridmin.Y())/gridsize.Y())),
int(floor((vect.X()-gridmin.X())/gridsize.X())));
}
Vector3dC GetVect(const PixelC & pxl) const
{
return Vector3dC ((pxl.Col()+0.5)*gridsize.X()+gridmin.X(),
(pxl.Row()+0.5)*gridsize.Y()+gridmin.Y(),
f_data[pxl]);
}
The conversion from to a ByteRangeC uses the same scheme for z noting that
the range of valid pixels is 1..255, "nrows"=255.
A vector range image may contain any vector in any pixel. If the
operation MaptoGrid is called, however each pixel must contain a
vector in the bin.
Any conversion from a vector representation will result in a rounding
down of the x and y values to the grid positions. To compensate for this
conversion from byte to vector will round up the positions to the centre
of the grid boxes.
All loads are soft except Load, soft means no exit on error.
A left hand coordinate system is used with x and y increasing horizontally
and vertically, respectively (col,row). z increases away from the camera
with the result that when viewed using normal image viewers, greater
distances will appear brighter unless photometric inversion is employed.
Files that can be read .pgm .dep .nrcc .txt .ris .vec .jrc .XYZim
written .pgm .dep .ris
DEPENDENCIES
------------
Range.def depends on:
Polops.def, Mimage.def, Mpxl.def, Marr.def and Mopt.def.
public ByteRangeC
public FloatRangeC
public VectRangeC
|
With Tags : How the author intended it to be viewed |
Comments:
BaseRangeC is a virtual abstract base class from which ByteRangeC,
FloatRangeC and VectRangeC will be inherited.
The i/o routines do have basic error checks.
A valid image point is one in which a range measurement is available.
How it is stored is dependent on the data structure but can be checked
by calling the function IsValid(). In byte format, 0 is invalid and
in vector format, z=-MAXFLOAT is invalid.
Range data is much more complicated than image data. It can be
sampled on a regular grid or not, the grid spacings may vary.
Together ByteRangeC, FloatRangeC and VectRangeC provide a powerful
set of functionality. For accurate results it is important to understand
precisely how the system is set up.
Firstly we explain the conventions for "gridded data". Consider a
4 pixel image row or column.
--- <-- 0.0 xgridmin=0.0
| ____ box center = 0.5
|
___ <-- 1.0
|
|
___ <-- 2.0
|
|
___ <-- 3.0 xgridmax=3.0
|
|
___ <-- 4.0
There are nrows=4 rows, i.e. r=0..3=nrows-1. Each bin hase size 1
and the total range is 0.0 - 3.9999999.
For gridded data the pixels are deemed to be in the centers of the boxes,
i.e. at 0.5, 1.5, 2.5, 3.5.
With each range image, the minimum and maximum x, y and z values are
stored. In each case, the values are obtained by scanning all of the
valid image points and finding the extremes in each dimension. These
values are kept in xmin,xmax,ymin,ymax,zmin,zmax.
For conversions between row and column and x and y we use
gridxmin,gridxmax,gridymin,gridymax. They are defined as shown above in the
picture. In this example
For gridded data the xgridmin=0.0 xgridmax=3.0,
xmin=0.5 xmax=3.5
asuming valid pixels in the border rows.
These values are obtained if possible from the data file.
To summarize the conversion is as follows:
gridsize.X = (gridmax.X - gridmin.X) / (ncols-1)
PixelC OfVect(const Vector3dC vect) const
{
return PixelC (int(floor((vect.Y()-gridmin.Y())/gridsize.Y())),
int(floor((vect.X()-gridmin.X())/gridsize.X())));
}
Vector3dC GetVect(const PixelC & pxl) const
{
return Vector3dC ((pxl.Col()+0.5)*gridsize.X()+gridmin.X(),
(pxl.Row()+0.5)*gridsize.Y()+gridmin.Y(),
f_data[pxl]);
}
The conversion from to a ByteRangeC uses the same scheme for z noting that
the range of valid pixels is 1..255, "nrows"=255.
A vector range image may contain any vector in any pixel. If the
operation MaptoGrid is called, however each pixel must contain a
vector in the bin.
Any conversion from a vector representation will result in a rounding
down of the x and y values to the grid positions. To compensate for this
conversion from byte to vector will round up the positions to the centre
of the grid boxes.
All loads are soft except Load, soft means no exit on error.
A left hand coordinate system is used with x and y increasing horizontally
and vertically, respectively (col,row). z increases away from the camera
with the result that when viewed using normal image viewers, greater
distances will appear brighter unless photometric inversion is employed.
Files that can be read .pgm .dep .ris .nrcc .txt .vec .jrc .XYZim
Files that can be written .pgm .dep .ris
|
As you can see there is a massive difference in the appearance and presentation
of the comments for this Class.
To give you an idea of how easy it is to add the tags, here's an extract of the
header file which produced the above documentation.
Extract Of Header File |
// -------------------------------------------------------------------------
// ********** BaseRangeC *************************************************
// -------------------------------------------------------------------------
//: Base class for range images.
//
// BaseRangeC is a virtual abstract base class from which ByteRangeC,
// FloatRangeC and VectRangeC will be inherited.<p>
//
// The i/o routines do have basic error checks.<p>
//
// A valid image point is one in which a range measurement is available.
// How it is stored is dependent on the data structure but can be checked
// by calling the function IsValid(). In byte format, 0 is invalid and
// in vector format, z=-MAXFLOAT is invalid.<p>
//
// Range data is much more complicated than image data. It can be
// sampled on a regular grid or not, the grid spacings may vary.
// Together ByteRangeC, FloatRangeC and VectRangeC provide a powerful
// set of functionality. For accurate results it is important to understand
// precisely how the system is set up.<p>
//
// Firstly we explain the conventions for "gridded data". Consider a
// 4 pixel image row or column.<p>
//
// <pre>
// --- <-- 0.0 xgridmin=0.0
// | ____ box center = 0.5
// |
// ___ <-- 1.0
// |
// |
// ___ <-- 2.0
// |
// |
// ___ <-- 3.0 xgridmax=3.0
// |
// |
// ___ <-- 4.0
// </pre>
//
// There are nrows=4 rows, i.e. r=0..3=nrows-1. Each bin hase size 1
// and the total range is 0.0 - 3.9999999.
// For gridded data the pixels are deemed to be in the centers of the boxes,
// i.e. at 0.5, 1.5, 2.5, 3.5.<p>
//
// With each range image, the minimum and maximum x, y and z values are
// stored. In each case, the values are obtained by scanning all of the
// valid image points and finding the extremes in each dimension. These
// values are kept in xmin,xmax,ymin,ymax,zmin,zmax.<p>
//
// For conversions between row and column and x and y we use
// gridxmin,gridxmax,gridymin,gridymax. They are defined as shown above in the
// picture. In this example <p>
//
// <pre>
// For gridded data the xgridmin=0.0 xgridmax=3.0,
// xmin=0.5 xmax=3.5
// asuming valid pixels in the border rows.
// </pre>
//
// These values are obtained if possible from the data file.<p>
//
// To summarize the conversion is as follows:<p>
//
// gridsize.X = (gridmax.X - gridmin.X) / (ncols-1)
//
// <pre>
// PixelC OfVect(const Vector3dC vect) const
// {
// return PixelC (int(floor((vect.Y()-gridmin.Y())/gridsize.Y())),
// int(floor((vect.X()-gridmin.X())/gridsize.X())));
// }
//
// Vector3dC GetVect(const PixelC & pxl) const
// {
// return Vector3dC ((pxl.Col()+0.5)*gridsize.X()+gridmin.X(),
// (pxl.Row()+0.5)*gridsize.Y()+gridmin.Y(),
// f_data[pxl]);
// }
// </pre>
//
// The conversion from to a ByteRangeC uses the same scheme for z noting that
// the range of valid pixels is 1..255, "nrows"=255.<p>
//
// A vector range image may contain any vector in any pixel. If the
// operation MaptoGrid is called, however each pixel must contain a
// vector in the bin.<p>
//
// Any conversion from a vector representation will result in a rounding
// down of the x and y values to the grid positions. To compensate for this
// conversion from byte to vector will round up the positions to the centre
// of the grid boxes.<p>
//
// All loads are soft except Load, soft means no exit on error.<p>
//
// A left hand coordinate system is used with x and y increasing horizontally
// and vertically, respectively (col,row). z increases away from the camera
// with the result that when viewed using normal image viewers, greater
// distances will appear brighter unless photometric inversion is employed.<p>
//
// Files that can be read .pgm .dep .ris .nrcc .txt .vec .jrc .XYZim<p>
//
// Files that can be written .pgm .dep .ris<p>
class BaseRangeC
{
// CUT.
};
|
Final Notes
Tags put in comments are interpreted as HTML wherever you put them so you can
have markups for member function comments although this should be avoided for
the sake of readability. Note that the special comment types //!param:, //:-,
and //!bug: should be enough to allow most things to be expressed reasonably well.
|
|