From 61392d3b263843840e0c7dfbe5fd5d3961ba5d8e Mon Sep 17 00:00:00 2001
From: Luc Hermitte <luc.hermitte@c-s.fr>
Date: Tue, 26 Jun 2012 11:59:57 +0200
Subject: [PATCH] DOC: OTB-151/GeometriesProjectionFilter -- doxygen
---
.../OGRAdapters/otbGeometriesSet.cxx | 87 +++++++++++++------
.../OGRAdapters/otbGeometriesSet.h | 51 +++++++----
.../OGRAdapters/otbGeometriesSource.cxx | 8 +-
.../OGRAdapters/otbGeometriesSource.h | 36 ++++++--
.../otbGeometriesToGeometriesFilter.h | 1 +
5 files changed, 130 insertions(+), 53 deletions(-)
diff --git a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.cxx b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.cxx
index 5c6ad91a1e..d86c64cf27 100644
--- a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.cxx
+++ b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.cxx
@@ -25,33 +25,50 @@
/*===========================================================================*/
/*================================[ Helpers ]================================*/
/*===========================================================================*/
-template <typename DataType>
-inline
-DataType & getRef(typename itk::SmartPointer<DataType> const& ds)
-{
- assert(ds && "unexpected nil datasource");
- return *ds;
-}
+namespace otb { namespace ogr { namespace internal {
+
+/**\ingroup GeometryInternals
+ * Access shim: itk smart-pointer to reference.
+ * \param[in] ds itk smart pointer
+ * \return a reference to the pointee.
+ * \throw None
+ * \pre <tt>ds != 0</tt>
+ * \since OTB v 3.14.0
+ */
+template <typename DataType> inline
+ DataType & getRef(typename itk::SmartPointer<DataType> const& ds)
+ {
+ assert(ds && "unexpected nil datasource");
+ return *ds;
+ }
-#if 0
-template <typename DataType>
+/**\ingroup GeometryInternals
+ * Access shim: const layer to reference.
+ * \param[in] layer layer proxy
+ * \return the layer proxy
+ * \throw None
+ * \since OTB v 3.14.0
+ */
inline
-DataType const& getRef(typename DataType::ConstPointer ds)
-{
- assert(ds);
- return *ds;
-}
-#endif
-
otb::ogr::Layer const& getRef(otb::ogr::Layer const& layer)
-{
+ {
return layer;
-}
-
+ }
+
+/**\ingroup GeometryInternals
+ * Access shim: layer to reference.
+ * \param[in] layer layer proxy
+ * \return the layer proxy
+ * \throw None
+ * \since OTB v 3.14.0
+ */
+inline
otb::ogr::Layer & getRef(otb::ogr::Layer & layer)
-{
+ {
return layer;
-}
+ }
+} } } // otb::ogr::internal namespaces
+
/*===========================================================================*/
/*=======================[ Setting and construction ]========================*/
@@ -111,23 +128,38 @@ void otb::GeometriesSet::Set(ogr::DataSource::Pointer datasource)
/*===========================================================================*/
/*=================================[ IsSet ]=================================*/
/*===========================================================================*/
+namespace otb { namespace ogr { namespace internal {
+/**\ingroup GeometryInternals
+ * Visitor (functor) to test whether a geometries set is non-null.
+ * \param[in] gs geometries set
+ * \throw None
+ * \since OTB v 3.14.0
+ */
struct IsSetTester : boost::static_visitor<bool>
{
template <typename T>
- bool operator()(T const& gs) const
- {
- return getRef(gs);
- }
+ bool operator()(T const& gs) const
+ {
+ return getRef(gs);
+ }
};
+} } } // otb::ogr::internal namespaces
bool otb::GeometriesSet::IsSet() const
{
- return this->apply(IsSetTester());
+ return this->apply(ogr::internal::IsSetTester());
}
/*===========================================================================*/
/*===============================[ Printing ]================================*/
/*===========================================================================*/
+namespace otb { namespace ogr { namespace internal {
+/**\ingroup GeometryInternals
+ * Visitor (functor) to print a geometries set.
+ * \param[in] gs geometries set
+ * \throw None
+ * \since OTB v 3.14.0
+ */
struct Printer : boost::static_visitor<>
{
Printer(std::ostream& os, itk::Indent indent)
@@ -146,8 +178,9 @@ private:
std::ostream &m_os;
itk::Indent m_indent;
};
+} } } // otb::ogr::internal namespaces
void otb::GeometriesSet::PrintSelf(std::ostream& os, itk::Indent indent) const
{
- this->apply(Printer(os, indent));
+ this->apply(ogr::internal::Printer(os, indent));
}
diff --git a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.h b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.h
index cf26f0f9a0..49be82e9ba 100644
--- a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.h
+++ b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSet.h
@@ -24,11 +24,6 @@
#include "otbOGRDataSourceWrapper.h"
#include "otbImageReference.h"
-namespace itk
-{
-class MetaDataDictionary;
-}
-
namespace otb
{
/**\ingroup gGeometry
@@ -58,9 +53,9 @@ public:
/** ITK method for creation through the object factory. */
itkNewMacro(Self);
- /// Direct builder from an existing \c DataSource.
+ /// Direct builder from an existing \c otb::DataSource.
static Pointer New(ogr::DataSource::Pointer datasource);
- /// Direct builder from an existing \c Layer.
+ /// Direct builder from an existing \c otb::Layer.
static Pointer New(ogr::Layer layer);
//@}
@@ -71,21 +66,32 @@ public:
//@}
/**\name Application of a command to a geometries set, through a visitor
- * \note
- * As a \c GeometriesSet contains either a \c otb::ogr::DataSource, or a
- * \c otb::ogr::Layer, one needs to apply a function on either kind of data.
- * This can be done thanks to a specialization of \c boost::static_visitor<>
- * that has a const \c operator() that takes either one (or two in case of
- * binary visitors) \c DataSource or \c Layer as parameter.
*/
//@{
template <typename Visitor>
typename Visitor::result_type
+ /**
+ * Unary visiting function to apply a visitor on any kind of geometies set.
+ *
+ * As a \c GeometriesSet contains either a \c otb::ogr::DataSource, or a \c
+ * otb::ogr::Layer, one needs to apply a function on either kind of data.
+ * This can be done thanks to a specialization of \c boost::static_visitor<>
+ * that has a const \c operator() that takes either one (or two in case of
+ * binary visitors) \c otb::DataSource or \c otb::Layer as parameter(s).
+ *
+ * \throw Whatever is thrown by the actual visitor.
+ * \tparam Visitor type of the visitor functor.
+ * \param[in] visitor Functor visitor that shal derive from \c
+ * boost::static_visitor.
+ */
apply(Visitor const& visitor)
{
return boost::apply_visitor(visitor, m_GeometriesSet);
}
+ /**
+ * \copydoc apply(Visitor const& visitor)
+ */
template <typename Visitor>
typename Visitor::result_type
apply(Visitor const& visitor) const
@@ -93,6 +99,12 @@ public:
return boost::apply_visitor(visitor, m_GeometriesSet);
}
+ /**
+ * Binary visiting function to apply a visitor on any kind of geometies set.
+ * \copydetails apply(Visitor const& visitor)
+ * \param[in] visitable other geometries set to visit along side with the
+ * current geometries set instance.
+ */
template <typename Visitor>
typename Visitor::result_type
apply(Visitor const& visitor, Self & visitable)
@@ -100,6 +112,9 @@ public:
return boost::apply_visitor(visitor, m_GeometriesSet, visitable.m_GeometriesSet);
}
+ /**
+ * \copydoc apply(Visitor const& visitor, Self& visitable)
+ */
template <typename Visitor>
typename Visitor::result_type
apply(Visitor const& visitor, Self /*const*/& visitable) const
@@ -116,10 +131,10 @@ public:
/**\name Image reference (spacing + origin) */
//@{
typedef ogr::ImageReference<double> ImageReference;
- /** imageReference setter. */
+ /** \em ImageReference setter. */
void SetImageReference(ImageReference const& imageReference)
{ m_ImageReference = imageReference; }
- /** imageReference getter. */
+ /** \em ImageReference getter. */
ImageReference const& GetImageReference() const
{ return m_ImageReference; }
//@}
@@ -128,15 +143,15 @@ protected:
/** Default constructor.
* This actual geometries set is an in-memory \c otb::ogr::DataSource.
* It needs to be set to a set of geometries if you expect to serialize it or
- * work on a \c Layer.
+ * work on a \c otb::Layer.
*
* When using this construction path, you'll likelly need to \c Set() the
* actual geometries set.
*/
GeometriesSet();
- /** Init constructor from a \c DataSource. */
+ /** Init constructor from a \c otb::DataSource. */
GeometriesSet(ogr::DataSource::Pointer datasource);
- /** Init constructor from a \c Layer. */
+ /** Init constructor from a \c otb::Layer. */
GeometriesSet(ogr::Layer layer);
/** Destructor. */
diff --git a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.cxx b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.cxx
index 24ffcdca9d..1acec8eb04 100644
--- a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.cxx
+++ b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.cxx
@@ -61,7 +61,8 @@ void otb::GeometriesSource::SetOutput(OutputGeometriesType* output, unsigned int
Superclass::SetNthOutput(idx, output);
}
-/*virtual*/ void otb::GeometriesSource::DoAllocateOutputs()
+/*virtual*/
+void otb::GeometriesSource::DoAllocateOutputs()
{
// The default behaviour is to prepare a in-memory OGR datasource in case
// filters are piped.
@@ -72,10 +73,13 @@ void otb::GeometriesSource::SetOutput(OutputGeometriesType* output, unsigned int
GeometriesSet::Pointer gs = GeometriesSet::New(); // in-memory DataSource
assert(gs);
this->SetOutput(gs);
+ ///\todo Check whether we need to increase the count of the \c GeometriesSet as
+ ///it'll get reelased at the end of function the scope.
}
}
-/*virtual*/ void otb::GeometriesSource::PrepareOutputs()
+/*virtual*/
+void otb::GeometriesSource::PrepareOutputs()
{
DoAllocateOutputs();
Superclass::PrepareOutputs();
diff --git a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.h b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.h
index bef7b13c42..e73e77a13d 100644
--- a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.h
+++ b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesSource.h
@@ -36,7 +36,6 @@ class GeometriesSet;
* \ingroup gGeometry Filters
* Filters of geometries sets.
*/
-
namespace otb
{
@@ -44,7 +43,22 @@ namespace otb
* \class GeometriesSource
* Source of geometries & Root of the geometries filters hierarchy.
* This class provides a kind of \em reader for geometries sets.
- * \todo: disable Graft
+ *
+ * Unlike others filters, the \em output has to be built from outside and given
+ * to the \c GeometriesSource. If no \em output has been defined at the moment
+ * the filter begins processing, by default the \c ogr::DataSource will have
+ * have an \em in-memory storage.
+ *
+ * \internal
+ * This particular behaviour is the consequence that, to exist, a \c
+ * ogr::DataSource needs to know how it is stored. We could have permitted to
+ * work on an \em in-memory \c ogr::DataSource, and then store the result into
+ * another \em on-disk \c ogr::DataSource. This wouldn't have been efficient at
+ * all. Hence the design adopted.
+ *
+ * \note As OGR data sources don't support multiple re-rentrant access, a \c
+ * ogr::DataSource can't be grafted, and as a consequence, \c GeometriesSource
+ * subtypes can't be grafted as well.
* \since OTB v 3.14.0
*/
class ITK_EXPORT GeometriesSource : public itk::ProcessObject, boost::noncopyable
@@ -81,17 +95,27 @@ public:
/** Overriding \c GetOutput() functions */
virtual OutputGeometriesType* GetOutput(unsigned int idx);
+ /**
+ * Output mutator.
+ * \param[in,out] output \c GeometriesSource where output result will be
+ * written.
+ * \param[in] idx index of the output assigned to the \c GeometriesSource.
+ *
+ * \throw std::bad_alloc if no new output can be added.
+ */
virtual void SetOutput(OutputGeometriesType* output, unsigned int idx = 0);
//@}
- /** Specialized hook for \c GeometriesSource.
- * Makes sure the output(s) is (/are) allocated before initializing them.
+ /** \c ProcessObject hook Specialized for \c GeometriesSource.
+ * This function makes sure the output(s) is (/are) allocated before
+ * initializing them.
+ * \post <tt>GetOutput() != NULL</tt>
*/
virtual void PrepareOutputs();
protected:
/** Default constructor.
- * \post Required number of outputs = 1
+ * \post Required number of outputs == 1
*/
GeometriesSource();
/** Destructor.
@@ -101,7 +125,7 @@ protected:
/** Ensures that the output geometries are allocated before processing.
* If the output hasn't been set, at this point, the default output geometries
- * set will an <em>in-memory</em> \c DataSource.
+ * set will be an <em>in-memory</em> \c ogr::DataSource.
* \post <tt>GetOutput() != NULL</tt>
*/
virtual void DoAllocateOutputs();
diff --git a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesToGeometriesFilter.h b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesToGeometriesFilter.h
index 1c114d21b8..a3aa7840fa 100644
--- a/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesToGeometriesFilter.h
+++ b/Code/UtilitiesAdapters/OGRAdapters/otbGeometriesToGeometriesFilter.h
@@ -80,6 +80,7 @@ protected:
private:
void Process(OutputGeometriesType &inout);
void Process(InputGeometriesType const& source, OutputGeometriesType &destination);
+
/**\name Filter specialization hooks.
* Filter specialization hooks.
* These functions are meant to be specialized by the actual filter.
--
GitLab