Move 'gdal vector geom' subcommands directly under 'gdal vector', and rename 'set-type' as 'set-geom-type' (#12439)

* Add GDALAlgorithm::IsHidden() and WarnIfDeprecated()

* gdal raster/vector pipeline: do not show hidden algorithms in usage

* Move 'gdal vector geom' subcommands directly under 'gdal vector', and rename 'set-type' as 'set-geom-type'

The old path can still be used in 3.12, but with a runtime message at
Run() time advertizing that it will be removed in 3.13

Fixes #12422

Author: rouault

MIGRATION_GUIDE.TXT

@@ -1,3 +1,16 @@
+MIGRATION GUIDE FROM GDAL 3.11 to GDAL 3.12
+-------------------------------------------
+
+- The following changes have been done to the "gdal" command line interface:
+
+  * Sub-commands "buffer", "explode-collections", "make-valid", "segmentize",
+    "simplify", "swap-xy" of "gdal vector geom" are now directly available
+    under "gdal vector". Support for the old location is kept for 3.12, but
+    will be definitely removed in 3.13.
+  * Furthermore, sub-command "set-type" of "gdal vector geom" is renamed as
+    "set-geom-type" and also placed under "gdal vector".
+
+
 MIGRATION GUIDE FROM GDAL 3.10 to GDAL 3.11
 -------------------------------------------
 

apps/CMakeLists.txt

@@ -72,14 +72,14 @@ add_library(
   gdalalg_vector_read.cpp
   gdalalg_vector_filter.cpp
   gdalalg_vector_geom.cpp
-  gdalalg_vector_geom_set_type.cpp
-  gdalalg_vector_geom_explode_collections.cpp
-  gdalalg_vector_geom_make_valid.cpp
-  gdalalg_vector_geom_segmentize.cpp
-  gdalalg_vector_geom_simplify.cpp
-  gdalalg_vector_geom_simplify_coverage.cpp
-  gdalalg_vector_geom_buffer.cpp
-  gdalalg_vector_geom_swap_xy.cpp
+  gdalalg_vector_set_geom_type.cpp
+  gdalalg_vector_explode_collections.cpp
+  gdalalg_vector_make_valid.cpp
+  gdalalg_vector_segmentize.cpp
+  gdalalg_vector_simplify.cpp
+  gdalalg_vector_simplify_coverage.cpp
+  gdalalg_vector_buffer.cpp
+  gdalalg_vector_swap_xy.cpp
   gdalalg_vector_grid.cpp
   gdalalg_vector_grid_average.cpp
   gdalalg_vector_grid_data_metrics.cpp

apps/gdalalg_abstract_pipeline.h

@@ -463,9 +463,12 @@ std::string GDALAbstractPipelineAlgorithm<StepAlgorithm>::GetUsageAsJSON() const
     for (const std::string &name : m_stepRegistry.GetNames())
     {
         auto alg = GetStepAlg(name);
-        CPLJSONDocument oStepDoc;
-        CPL_IGNORE_RET_VAL(oStepDoc.LoadMemory(alg->GetUsageAsJSON()));
-        jPipelineSteps.Add(oStepDoc.GetRoot());
+        if (!alg->IsHidden())
+        {
+            CPLJSONDocument oStepDoc;
+            CPL_IGNORE_RET_VAL(oStepDoc.LoadMemory(alg->GetUsageAsJSON()));
+            jPipelineSteps.Add(oStepDoc.GetRoot());
+        }
     }
     oDoc.GetRoot().Add("pipeline_algorithms", jPipelineSteps);
 

apps/gdalalg_raster_pipeline.cpp

@@ -686,10 +686,13 @@ std::string GDALRasterPipelineAlgorithm::GetUsageForCLI(
         if (name != GDALRasterReadAlgorithm::NAME &&
             name != GDALRasterWriteAlgorithm::NAME)
         {
-            ret += '\n';
             auto alg = GetStepAlg(name);
-            alg->SetCallPath({name});
-            ret += alg->GetUsageForCLI(shortUsage, stepUsageOptions);
+            if (!alg->IsHidden())
+            {
+                ret += '\n';
+                alg->SetCallPath({name});
+                ret += alg->GetUsageForCLI(shortUsage, stepUsageOptions);
+            }
         }
     }
     {

apps/gdalalg_vector.cpp

@@ -13,19 +13,27 @@
 #include "gdalalgorithm.h"
 
 #include "gdalalg_vector_info.h"
+#include "gdalalg_vector_buffer.h"
 #include "gdalalg_vector_clip.h"
 #include "gdalalg_vector_concat.h"
 #include "gdalalg_vector_convert.h"
 #include "gdalalg_vector_edit.h"
+#include "gdalalg_vector_explode_collections.h"
 #include "gdalalg_vector_geom.h"
 #include "gdalalg_vector_grid.h"
 #include "gdalalg_vector_layer_algebra.h"
 #include "gdalalg_vector_pipeline.h"
 #include "gdalalg_vector_rasterize.h"
 #include "gdalalg_vector_filter.h"
 #include "gdalalg_vector_reproject.h"
+#include "gdalalg_vector_segmentize.h"
 #include "gdalalg_vector_select.h"
+#include "gdalalg_vector_set_geom_type.h"
+#include "gdalalg_vector_simplify.h"
+#include "gdalalg_vector_simplify_coverage.h"
 #include "gdalalg_vector_sql.h"
+#include "gdalalg_vector_make_valid.h"
+#include "gdalalg_vector_swap_xy.h"
 
 #include "gdal_priv.h"
 
@@ -53,19 +61,27 @@ class GDALVectorAlgorithm final : public GDALAlgorithm
         AddOutputStringArg(&m_output);
 
         RegisterSubAlgorithm<GDALVectorInfoAlgorithm>();
+        RegisterSubAlgorithm<GDALVectorBufferAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorClipAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorConcatAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorConvertAlgorithm>();
         RegisterSubAlgorithm<GDALVectorEditAlgorithmStandalone>();
+        RegisterSubAlgorithm<GDALVectorExplodeCollectionsAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorGridAlgorithm>();
         RegisterSubAlgorithm<GDALVectorRasterizeAlgorithm>();
         RegisterSubAlgorithm<GDALVectorPipelineAlgorithm>();
         RegisterSubAlgorithm<GDALVectorFilterAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorGeomAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorLayerAlgebraAlgorithm>();
+        RegisterSubAlgorithm<GDALVectorMakeValidAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorReprojectAlgorithmStandalone>();
+        RegisterSubAlgorithm<GDALVectorSegmentizeAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorSelectAlgorithmStandalone>();
+        RegisterSubAlgorithm<GDALVectorSetGeomTypeAlgorithmStandalone>();
+        RegisterSubAlgorithm<GDALVectorSimplifyAlgorithmStandalone>();
+        RegisterSubAlgorithm<GDALVectorSimplifyCoverageAlgorithmStandalone>();
         RegisterSubAlgorithm<GDALVectorSQLAlgorithmStandalone>();
+        RegisterSubAlgorithm<GDALVectorSwapXYAlgorithmStandalone>();
     }
 
   private:

apps/gdalalg_vector_geom_buffer.cpp renamed to apps/gdalalg_vector_buffer.cpp

@@ -1,7 +1,7 @@
 /******************************************************************************
  *
  * Project:  GDAL
- * Purpose:  "gdal vector geom buffer"
+ * Purpose:  "gdal vector buffer"
  * Author:   Even Rouault <even dot rouault at spatialys.com>
  *
  ******************************************************************************
@@ -10,7 +10,7 @@
  * SPDX-License-Identifier: MIT
  ****************************************************************************/
 
-#include "gdalalg_vector_geom_buffer.h"
+#include "gdalalg_vector_buffer.h"
 
 #include "gdal_priv.h"
 #include "ogrsf_frmts.h"
@@ -22,11 +22,10 @@
 #endif
 
 /************************************************************************/
-/*                  GDALVectorGeomBufferAlgorithm()                     */
+/*                    GDALVectorBufferAlgorithm()                       */
 /************************************************************************/
 
-GDALVectorGeomBufferAlgorithm::GDALVectorGeomBufferAlgorithm(
-    bool standaloneStep)
+GDALVectorBufferAlgorithm::GDALVectorBufferAlgorithm(bool standaloneStep)
     : GDALVectorGeomAbstractAlgorithm(NAME, DESCRIPTION, HELP_URL,
                                       standaloneStep, m_opts)
 {
@@ -63,16 +62,16 @@ namespace
 {
 
 /************************************************************************/
-/*                   GDALVectorGeomBufferAlgorithmLayer                 */
+/*                     GDALVectorBufferAlgorithmLayer                   */
 /************************************************************************/
 
-class GDALVectorGeomBufferAlgorithmLayer final
-    : public GDALVectorGeomOneToOneAlgorithmLayer<GDALVectorGeomBufferAlgorithm>
+class GDALVectorBufferAlgorithmLayer final
+    : public GDALVectorGeomOneToOneAlgorithmLayer<GDALVectorBufferAlgorithm>
 {
   public:
-    GDALVectorGeomBufferAlgorithmLayer(
-        OGRLayer &oSrcLayer, const GDALVectorGeomBufferAlgorithm::Options &opts)
-        : GDALVectorGeomOneToOneAlgorithmLayer<GDALVectorGeomBufferAlgorithm>(
+    GDALVectorBufferAlgorithmLayer(
+        OGRLayer &oSrcLayer, const GDALVectorBufferAlgorithm::Options &opts)
+        : GDALVectorGeomOneToOneAlgorithmLayer<GDALVectorBufferAlgorithm>(
               oSrcLayer, opts)
     {
         m_aosBufferOptions.SetNameValue("ENDCAP_STYLE",
@@ -100,8 +99,7 @@ class GDALVectorGeomBufferAlgorithmLayer final
 /*                          TranslateFeature()                          */
 /************************************************************************/
 
-std::unique_ptr<OGRFeature>
-GDALVectorGeomBufferAlgorithmLayer::TranslateFeature(
+std::unique_ptr<OGRFeature> GDALVectorBufferAlgorithmLayer::TranslateFeature(
     std::unique_ptr<OGRFeature> poSrcFeature) const
 {
     const int nGeomFieldCount = poSrcFeature->GetGeomFieldCount();
@@ -133,28 +131,25 @@ GDALVectorGeomBufferAlgorithmLayer::TranslateFeature(
 #endif  // HAVE_GEOS
 
 /************************************************************************/
-/*            GDALVectorGeomBufferAlgorithm::CreateAlgLayer()           */
+/*              GDALVectorBufferAlgorithm::CreateAlgLayer()             */
 /************************************************************************/
 
 std::unique_ptr<OGRLayerWithTranslateFeature>
-GDALVectorGeomBufferAlgorithm::CreateAlgLayer(
-    [[maybe_unused]] OGRLayer &srcLayer)
+GDALVectorBufferAlgorithm::CreateAlgLayer([[maybe_unused]] OGRLayer &srcLayer)
 {
 #ifdef HAVE_GEOS
-    return std::make_unique<GDALVectorGeomBufferAlgorithmLayer>(srcLayer,
-                                                                m_opts);
+    return std::make_unique<GDALVectorBufferAlgorithmLayer>(srcLayer, m_opts);
 #else
     CPLAssert(false);
     return nullptr;
 #endif
 }
 
 /************************************************************************/
-/*                GDALVectorGeomBufferAlgorithm::RunStep()              */
+/*                  GDALVectorBufferAlgorithm::RunStep()                */
 /************************************************************************/
 
-bool GDALVectorGeomBufferAlgorithm::RunStep(
-    GDALVectorPipelineStepRunContext &ctxt)
+bool GDALVectorBufferAlgorithm::RunStep(GDALVectorPipelineStepRunContext &ctxt)
 {
 #ifdef HAVE_GEOS
     if (m_opts.m_side == "right")

apps/gdalalg_vector_geom_buffer.h renamed to apps/gdalalg_vector_buffer.h

@@ -1,7 +1,7 @@
 /******************************************************************************
  *
  * Project:  GDAL
- * Purpose:  "gdal vector geom buffer"
+ * Purpose:  "gdal vector buffer"
  * Author:   Even Rouault <even dot rouault at spatialys.com>
  *
  ******************************************************************************
@@ -10,26 +10,25 @@
  * SPDX-License-Identifier: MIT
  ****************************************************************************/
 
-#ifndef GDALALG_VECTOR_GEOM_BUFFER_INCLUDED
-#define GDALALG_VECTOR_GEOM_BUFFER_INCLUDED
+#ifndef GDALALG_VECTOR_BUFFER_INCLUDED
+#define GDALALG_VECTOR_BUFFER_INCLUDED
 
 #include "gdalalg_vector_geom.h"
 
 //! @cond Doxygen_Suppress
 
 /************************************************************************/
-/*                  GDALVectorGeomBufferAlgorithm                       */
+/*                    GDALVectorBufferAlgorithm                         */
 /************************************************************************/
 
-class GDALVectorGeomBufferAlgorithm final
+class GDALVectorBufferAlgorithm /* non final */
     : public GDALVectorGeomAbstractAlgorithm
 {
   public:
     static constexpr const char *NAME = "buffer";
     static constexpr const char *DESCRIPTION =
         "Compute a buffer around geometries of a vector dataset.";
-    static constexpr const char *HELP_URL =
-        "/programs/gdal_vector_geom_buffer.html";
+    static constexpr const char *HELP_URL = "/programs/gdal_vector_buffer.html";
 
     struct Options : public GDALVectorGeomAbstractAlgorithm::OptionsBase
     {
@@ -44,14 +43,28 @@ class GDALVectorGeomBufferAlgorithm final
     std::unique_ptr<OGRLayerWithTranslateFeature>
     CreateAlgLayer(OGRLayer &srcLayer) override;
 
-    explicit GDALVectorGeomBufferAlgorithm(bool standaloneStep);
+    explicit GDALVectorBufferAlgorithm(bool standaloneStep = false);
 
   private:
     bool RunStep(GDALVectorPipelineStepRunContext &ctxt) override;
 
     Options m_opts{};
 };
 
+/************************************************************************/
+/*                    GDALVectorBufferAlgorithmStandalone               */
+/************************************************************************/
+
+class GDALVectorBufferAlgorithmStandalone final
+    : public GDALVectorBufferAlgorithm
+{
+  public:
+    GDALVectorBufferAlgorithmStandalone()
+        : GDALVectorBufferAlgorithm(/* standaloneStep = */ true)
+    {
+    }
+};
+
 //! @endcond
 
-#endif /* GDALALG_VECTOR_GEOM_BUFFER_INCLUDED */
+#endif /* GDALALG_VECTOR_BUFFER_INCLUDED */