Commit 61392d3b authored by Luc Hermitte's avatar Luc Hermitte

DOC: OTB-151/GeometriesProjectionFilter -- doxygen

parent 4b9dc1fd
......@@ -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));
}
......@@ -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. */
......
......@@ -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();
......
......@@ -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();
......
......@@ -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.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment