ENH: OTB-134/OGR: other Feature function + some dox

Code/UtilitiesAdapters/OGRAdapters/otbOGRFeatureWrapper.cxx

@@ -23,6 +23,7 @@
 #include <boost/bind.hpp>
 #include <boost/make_shared.hpp>
 #include "ogr_feature.h"
+#include "itkMacro.h"
 
 #include "otbOGRFieldWrapper.h"
 /*===========================================================================*/
@@ -56,6 +57,18 @@ otb::ogr::Feature otb::ogr::Feature::clone() const
   return res;
 }
 
+void otb::ogr::Feature::SetFrom(Feature const& rhs, bool mustForgive)
+{
+  CheckInvariants();
+  m_Feature->SetFrom(&rhs.ogr(), mustForgive);
+}
+
+void otb::ogr::Feature::SetFrom(Feature const& rhs, int * map, bool mustForgive)
+{
+  CheckInvariants();
+  m_Feature->SetFrom(&rhs.ogr(), map, mustForgive);
+}
+
 /*===========================================================================*/
 /*=================================[ Misc ]==================================*/
 /*===========================================================================*/
@@ -97,11 +110,70 @@ size_t otb::ogr::Feature::GetSize() const {
 
 otb::ogr::Field otb::ogr::Feature::operator[](size_t index)
 {
-    Field field(*this, index);
-    return field;
+  CheckInvariants();
+  Field field(*this, index);
+  return field;
 }
 
 otb::ogr::Field const otb::ogr::Feature::operator[](size_t index) const
 {
   return const_cast<Feature*>(this)->operator[](index);
 }
+
+otb::ogr::Field otb::ogr::Feature::operator[](std::string const& name)
+{
+  CheckInvariants();
+  int index = m_Feature->GetFieldIndex(name.c_str());
+  if (index < 0)
+    {
+    itkGenericExceptionMacro(<<"No field named <"<<name<<"> in feature");
+    }
+  return this->operator[](index);
+}
+
+otb::ogr::Field const otb::ogr::Feature::operator[](std::string const& name) const
+{
+  return const_cast<Feature*>(this)->operator[](name);
+}
+
+otb::ogr::FieldDefn otb::ogr::Feature::GetFieldDefn(size_t index) const
+{
+  CheckInvariants();
+  return FieldDefn(*m_Feature->GetFieldDefnRef(index));
+}
+
+otb::ogr::FieldDefn otb::ogr::Feature::GetFieldDefn(std::string const& name) const
+{
+  CheckInvariants();
+  int index = m_Feature->GetFieldIndex(name.c_str());
+  if (index < 0)
+    {
+    itkGenericExceptionMacro(<<"No field named <"<<name<<"> in feature");
+    }
+  return this->GetFieldDefn(index);
+}
+
+/*===========================================================================*/
+/*==============================[ Properties ]===============================*/
+/*===========================================================================*/
+long otb::ogr::Feature::GetFID() const
+{
+  CheckInvariants();
+  return m_Feature->GetFID();
+}
+
+void otb::ogr::Feature::SetFID(long fid)
+{
+  CheckInvariants();
+  const OGRErr res = m_Feature->SetFID(fid);
+  if (res != OGRERR_NONE)
+    {
+    itkGenericExceptionMacro(<<"Cannot Set FID to "<<fid<<" for feature: " << res);
+    }
+}
+
+OGRFeatureDefn&  otb::ogr::Feature::GetDefn() const
+{
+  CheckInvariants();
+  return *m_Feature->GetDefnRef();
+}

Code/UtilitiesAdapters/OGRAdapters/otbOGRFeatureWrapper.h

@@ -34,8 +34,12 @@ class Feature;
 bool operator==(Feature const& lhs, Feature const& rhs);
 
 /**\ingroup Geometry
- * \class Feature
+ * \class Feature proxy class.
  * \invariant <tt>m_Feature != 0</tt>
+ *
+ * \note \c Feature assignment will just make one \c Feature proxy point to
+ * another \c OGRFeature. In order to truly assign from one to another, use \c
+ * SetFrom.
  */
 class Feature
   {
@@ -53,11 +57,22 @@ public:
   boost::shared_ptr<OGRFeature>      & sptr()       {return m_Feature; }
   boost::shared_ptr<OGRFeature> const& sptr() const {return m_Feature; }
 
+  void SetFrom(Feature const& rhs, bool mustForgive = true);
+  void SetFrom(Feature const& rhs, int *map, bool mustForgive = true);
+
+  long GetFID() const;
+  void SetFID(long fid);
+  OGRFeatureDefn& GetDefn() const;
+
   /**\name Fields */
   //@{
   size_t GetSize() const;
   Field       operator[](size_t index);
   Field const operator[](size_t index) const;
+  Field       operator[](std::string const& name);
+  Field const operator[](std::string const& name) const;
+  FieldDefn   GetFieldDefn(size_t index) const;
+  FieldDefn   GetFieldDefn(std::string const& name) const;
   //@}
 
   friend bool otb::ogr::operator==(Feature const& lhs, Feature const& rhs);

Code/UtilitiesAdapters/OGRAdapters/otbOGRFieldWrapper.cxx

@@ -131,3 +131,15 @@ std::ostream & otb::ogr::Field::PrintSelf(
   os << "\n";
   return os;
 }
+
+bool otb::ogr::Field::HasBeenSet() const
+{
+  assert(m_Feature);
+  return m_Feature->IsFieldSet(m_index);
+}
+
+void otb::ogr::Field::Unset() const
+{
+  assert(m_Feature);
+  m_Feature->UnsetField(m_index);
+}

Code/UtilitiesAdapters/OGRAdapters/otbOGRFieldWrapper.h

@@ -39,8 +39,20 @@ class OGRFieldDefn;
 
 namespace otb { namespace ogr {
 
+/**\ingroup Geometry
+ * \defgroup GeometryInternals Geometry Internals
+ */
+
+/**\ingroup GeometryInternals
+ * Namespace used to host internal meta-prog definitions.
+ */
 namespace metaprog { // namespace metaprog
 using namespace boost::mpl;
+
+/**\ingroup GeometryInternals
+ * Associative map of C++ types to OGR field types (\c OGRFieldType).
+ * \internal Relies on Boost.MPL
+ */
 typedef boost::mpl::map
   < pair<int, int_<OFTInteger> >
   , pair<std::vector<int>, int_<OFTIntegerList> >
@@ -54,6 +66,17 @@ typedef boost::mpl::map
   // OFTDateTime
   > FieldType_Map;
 
+/**\ingroup GeometryInternals
+ * Type for hosting simple member-function pointers to field getters.
+ * \tparam T type of field according to OGR API.
+ * \tparam ptr_to_function member function pointer to a field getter from \c
+ *         OGRFeature.
+ * \tparam FinalReturnType type of the field according to OTB wrappers (default
+ * <tt> = T</tt>)
+ *
+ * \internal
+ * This is a hack to pass a member function pointer as template-parameter.
+ */
 template
   < typename T
   , T ( OGRFeature::*ptr_to_function )(int)
@@ -67,6 +90,17 @@ template
       }
     };
 
+/**\ingroup GeometryInternals
+ * Type for hosting simple member-function pointers to list-field getters.
+ * \tparam T type of field according to OGR API.
+ * \tparam ptr_to_function member function pointer to a list-field getter from
+ * \c OGRFeature.
+ * \tparam FinalReturnType type of the list-field according to OTB wrappers
+ * (default <tt> = std::vector<T></tt>)
+ *
+ * \internal
+ * This is a hack to pass a member function pointer as template-parameter.
+ */
 template
   < typename T
   , T const* ( OGRFeature::*ptr_to_function )(int, int*)
@@ -78,11 +112,16 @@ template
       {
       int nb = 0;
       T const* raw_container = (f.*ptr_to_function)(index, &nb);
-      FinalReturnType res(raw_container+0, raw_container+nb);
+      const FinalReturnType res(raw_container+0, raw_container+nb);
       return res;
       }
     };
 
+/**\ingroup GeometryInternals
+ * Associative map of OGR field types (\c OGRFieldType) to their associated
+ * getters.
+ * \internal Relies on Boost.MPL
+ */
 typedef map
   < pair<int_<OFTInteger>,     MemberGetterPtr<int,             &OGRFeature::GetFieldAsInteger> >
   , pair<int_<OFTIntegerList>, MemberContainerGetterPtr<int,    &OGRFeature::GetFieldAsIntegerList> >
@@ -94,6 +133,14 @@ typedef map
 
 } // namespace metaprog
 
+/**\ingroup Geometry
+ * \class FieldDefn
+ * \brief Encapsulation of \c OGRFieldDefn
+ * \invariant <tt>m_definition != 0</tt>
+ * \invariant \c m_definition lifetime is of the responsability of the owning \c
+ * \c OGRFeatureDefn.
+ * \sa OGRFieldDefn
+ */
 class FieldDefn
   {
 public:
@@ -149,6 +196,13 @@ template <> struct FieldDecodingTraitsGetter<std::string>
 /*=================================[ Field ]=================================*/
 /*===========================================================================*/
 class Feature;
+/**\ingroup Geometry
+ * \class Field
+ * \brief Encapsulation of \c OGRField
+ * Instances of \c Field are expected to be built from an existing \c Feature
+ * with which they'll share their owning \c OGRFeature.
+ * \sa OGRField
+ */
 class Field
   {
 public:
@@ -160,6 +214,9 @@ public:
   std::string GetName() const
     { return m_Definition.GetName(); }
 
+  bool HasBeenSet() const;
+  void Unset() const;
+
 #if 0
   template <typename T> void SetValue(T const& v)
     {