/src/gdal/apps/gdalalg_raster_index.cpp

Source
/******************************************************************************
 *
 * Project:  GDAL
 * Purpose:  gdal "raster index" subcommand
 * Author:   Even Rouault <even dot rouault at spatialys.com>
 *
 ******************************************************************************
 * Copyright (c) 2025, Even Rouault <even dot rouault at spatialys.com>
 *
 * SPDX-License-Identifier: MIT
 ****************************************************************************/

#include "gdalalg_raster_index.h"

#include "cpl_conv.h"
#include "gdal_priv.h"
#include "gdal_utils_priv.h"
#include "ogrsf_frmts.h"

//! @cond Doxygen_Suppress

#ifndef _
#define _(x) (x)
#endif

/************************************************************************/
/*         GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm()         */
/************************************************************************/

GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm()
    : GDALVectorOutputAbstractAlgorithm(NAME, DESCRIPTION, HELP_URL)
{
    AddProgressArg();
    AddInputDatasetArg(&m_inputDatasets, GDAL_OF_RASTER)
        .SetAutoOpenDataset(false)
        .SetDatasetInputFlags(GADV_NAME);
    GDALVectorOutputAbstractAlgorithm::AddAllOutputArgs();

    AddCommonOptions();

    AddArg("source-crs-field-name", 0,
           _("Name of the field to store the CRS of each dataset"),
           &m_sourceCrsName)
        .SetMinCharCount(1);
    AddArg("source-crs-format", 0,
           _("Format in which the CRS of each dataset must be written"),
           &m_sourceCrsFormat)
        .SetMinCharCount(1)
        .SetDefault(m_sourceCrsFormat)
        .SetChoices("auto", "WKT", "EPSG", "PROJ");
}

/************************************************************************/
/*         GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm()         */
/************************************************************************/

GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm(
    const std::string &name, const std::string &description,
    const std::string &helpURL)
    : GDALVectorOutputAbstractAlgorithm(name, description, helpURL)
{
}

/************************************************************************/
/*             GDALRasterIndexAlgorithm::AddCommonOptions()             */
/************************************************************************/

void GDALRasterIndexAlgorithm::AddCommonOptions()
{
    AddArg("recursive", 0,
           _("Whether input directories should be explored recursively."),
           &m_recursive);
    AddArg("filename-filter", 0,
           _("Pattern that the filenames in input directories should follow "
             "('*' and '?' wildcard)"),
           &m_filenameFilter);
    AddArg("min-pixel-size", 0,
           _("Minimum pixel size in term of geospatial extent per pixel "
             "(resolution) that a raster should have to be selected."),
           &m_minPixelSize)
        .SetMinValueExcluded(0);
    AddArg("max-pixel-size", 0,
           _("Maximum pixel size in term of geospatial extent per pixel "
             "(resolution) that a raster should have to be selected."),
           &m_maxPixelSize)
        .SetMinValueExcluded(0);
    AddArg("location-name", 0, _("Name of the field with the raster path"),
           &m_locationName)
        .SetDefault(m_locationName)
        .SetMinCharCount(1);
    AddAbsolutePathArg(
        &m_writeAbsolutePaths,
        _("Whether the path to the input datasets should be stored as an "
          "absolute path"));
    AddArg(GDAL_ARG_NAME_OUTPUT_CRS, 0, _("Output CRS"), &m_crs)
        .SetIsCRSArg()
        .AddHiddenAlias("dst-crs")
        .AddHiddenAlias("t_srs");

    {
        auto &arg =
            AddArg("metadata", 0, _("Add dataset metadata item"), &m_metadata)
                .SetMetaVar("<KEY>=<VALUE>")
                .SetPackedValuesAllowed(false);
        arg.AddValidationAction([this, &arg]()
                                { return ParseAndValidateKeyValue(arg); });
        arg.AddHiddenAlias("mo");
    }

    AddArg("skip-errors", 0, _("Skip errors related to input datasets"),
           &m_skipErrors);
    AddArg("profile", 0, _("Profile of output dataset"), &m_profile)
        .SetDefault(m_profile)
        .SetChoices(PROFILE_NONE, PROFILE_STAC_GEOPARQUET);
    AddArg("base-url", 0, _("Base URL for STAC-GeoParquet href"), &m_baseUrl);
    AddArg("id-method", 0, _("How to derive STAC-GeoParquet 'id'"), &m_idMethod)
        .SetDefault(m_idMethod)
        .SetChoices(ID_METHOD_FILENAME, ID_METHOD_MD5, ID_METHOD_METADATA_ITEM);
    AddArg("id-metadata-item", 0,
           _("Name of metadata item used to set STAC-GeoParquet 'id'"),
           &m_idMetadataItem)
        .SetDefault(m_idMetadataItem)
        .AddValidationAction(
            [this]()
            {
                m_idMethod = ID_METHOD_METADATA_ITEM;
                return true;
            });

    AddValidationAction(
        [this]()
        {
            if (m_profile == PROFILE_STAC_GEOPARQUET)
            {
                if (!m_outputFormat.empty() &&
                    !EQUAL(m_outputFormat.c_str(), "Parquet"))
                {
                    ReportError(CE_Failure, CPLE_NotSupported,
                                "STAC-GeoParquet profile is only compatible "
                                "with Parquet output format");
                    return false;
                }
                else if (m_outputFormat.empty() &&
                         !EQUAL(CPLGetExtensionSafe(
                                    m_outputDataset.GetName().c_str())
                                    .c_str(),
                                "parquet"))
                {
                    ReportError(CE_Failure, CPLE_NotSupported,
                                "STAC-GeoParquet profile is only compatible "
                                "with Parquet output format");
                    return false;
                }
                m_outputFormat = "Parquet";

                if (!m_crs.empty() && m_crs != "EPSG:4326")
                {
                    OGRSpatialReference oSRS;
                    CPL_IGNORE_RET_VAL(oSRS.SetFromUserInput(m_crs.c_str()));
                    const char *pszCelestialBodyName =
                        oSRS.GetCelestialBodyName();
                    // STAC-GeoParquet requires EPSG:4326, but let be nice
                    // with planetary use cases and allow a non-Earth geographic CRS...
                    if (!(pszCelestialBodyName &&
                          !EQUAL(pszCelestialBodyName, "Earth") &&
                          oSRS.IsGeographic()))
                    {
                        ReportError(
                            CE_Failure, CPLE_NotSupported,
                            "STAC-GeoParquet profile is only compatible "
                            "with --output-crs=EPSG:4326");
                        return false;
                    }
                }
                if (m_crs.empty())
                    m_crs = "EPSG:4326";
            }
            return true;
        });
}

/************************************************************************/
/*                 GDALRasterIndexAlgorithm::RunImpl()                  */
/************************************************************************/

bool GDALRasterIndexAlgorithm::RunImpl(GDALProgressFunc pfnProgress,
                                       void *pProgressData)
{
    CPLStringList aosSources;
    for (auto &srcDS : m_inputDatasets)
    {
        CPLAssert(!srcDS.GetDatasetRef());
        aosSources.push_back(srcDS.GetName());
    }

    auto setupRet = SetupOutputDataset();
    if (!setupRet.outDS)
        return false;

    if (!SetDefaultOutputLayerNameIfNeeded(setupRet.outDS))
        return false;

    CPLStringList aosOptions;
    aosOptions.push_back("--invoked-from-gdal-raster-index");

    if (m_profile != PROFILE_NONE)
    {
        aosOptions.push_back("-profile");
        aosOptions.push_back(m_profile);

        if (!m_baseUrl.empty())
        {
            aosOptions.push_back("--base-url");
            aosOptions.push_back(m_baseUrl);
        }

        aosOptions.push_back("--id-metadata-item");
        aosOptions.push_back(m_idMetadataItem);

        aosOptions.push_back("--id-method");
        aosOptions.push_back(m_idMethod);
    }

    if (m_skipErrors)
    {
        aosOptions.push_back("-skip_errors");
    }
    if (m_recursive)
    {
        aosOptions.push_back("-recursive");
    }
    for (const std::string &s : m_filenameFilter)
    {
        aosOptions.push_back("-filename_filter");
        aosOptions.push_back(s);
    }
    if (m_minPixelSize > 0)
    {
        aosOptions.push_back("-min_pixel_size");
        aosOptions.push_back(CPLSPrintf("%.17g", m_minPixelSize));
    }
    if (m_maxPixelSize > 0)
    {
        aosOptions.push_back("-max_pixel_size");
        aosOptions.push_back(CPLSPrintf("%.17g", m_maxPixelSize));
    }

    if (!m_outputLayerName.empty())
    {
        aosOptions.push_back("-lyr_name");
        aosOptions.push_back(m_outputLayerName);
    }

    aosOptions.push_back("-tileindex");
    aosOptions.push_back(m_locationName);

    if (m_writeAbsolutePaths)
    {
        aosOptions.push_back("-write_absolute_path");
    }
    if (m_crs.empty())
    {
        if (m_sourceCrsName.empty())
            aosOptions.push_back("-skip_different_projection");
    }
    else
    {
        aosOptions.push_back("-t_srs");
        aosOptions.push_back(m_crs);
    }
    if (!m_sourceCrsName.empty())
    {
        aosOptions.push_back("-src_srs_name");
        aosOptions.push_back(m_sourceCrsName);

        aosOptions.push_back("-src_srs_format");
        aosOptions.push_back(CPLString(m_sourceCrsFormat).toupper());
    }

    for (const std::string &s : m_metadata)
    {
        aosOptions.push_back("-mo");
        aosOptions.push_back(s);
    }

    if (!AddExtraOptions(aosOptions))
        return false;

    std::unique_ptr<GDALTileIndexOptions, decltype(&GDALTileIndexOptionsFree)>
        options(GDALTileIndexOptionsNew(aosOptions.List(), nullptr),
                GDALTileIndexOptionsFree);

    if (options)
    {
        GDALTileIndexOptionsSetProgress(options.get(), pfnProgress,
                                        pProgressData);
    }

    const bool ret =
        options && GDALTileIndexInternal(m_outputDataset.GetName().c_str(),
                                         GDALDataset::ToHandle(setupRet.outDS),
                                         OGRLayer::ToHandle(setupRet.layer),
                                         aosSources.size(), aosSources.List(),
                                         options.get(), nullptr) != nullptr;

    if (ret && setupRet.newDS)
    {
        m_outputDataset.Set(std::move(setupRet.newDS));
    }

    return ret;
}

//! @endcond

Coverage Report

Created: 2026-07-25 06:50

Line	Count	Source
1		/******************************************************************************
2		*
3		* Project: GDAL
4		* Purpose: gdal "raster index" subcommand
5		* Author: Even Rouault <even dot rouault at spatialys.com>
6		*
7		******************************************************************************
8		* Copyright (c) 2025, Even Rouault <even dot rouault at spatialys.com>
9		*
10		* SPDX-License-Identifier: MIT
11		****************************************************************************/
12
13		#include "gdalalg_raster_index.h"
14
15		#include "cpl_conv.h"
16		#include "gdal_priv.h"
17		#include "gdal_utils_priv.h"
18		#include "ogrsf_frmts.h"
19
20		//! @cond Doxygen_Suppress
21
22		#ifndef _
23	0	#define _(x) (x)
24		#endif
25
26		/************************************************************************/
27		/* GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm() */
28		/************************************************************************/
29
30		GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm()
31	0	: GDALVectorOutputAbstractAlgorithm(NAME, DESCRIPTION, HELP_URL)
32	0	{
33	0	AddProgressArg();
34	0	AddInputDatasetArg(&m_inputDatasets, GDAL_OF_RASTER)
35	0	.SetAutoOpenDataset(false)
36	0	.SetDatasetInputFlags(GADV_NAME);
37	0	GDALVectorOutputAbstractAlgorithm::AddAllOutputArgs();
38
39	0	AddCommonOptions();
40
41	0	AddArg("source-crs-field-name", 0,
42	0	_("Name of the field to store the CRS of each dataset"),
43	0	&m_sourceCrsName)
44	0	.SetMinCharCount(1);
45	0	AddArg("source-crs-format", 0,
46	0	_("Format in which the CRS of each dataset must be written"),
47	0	&m_sourceCrsFormat)
48	0	.SetMinCharCount(1)
49	0	.SetDefault(m_sourceCrsFormat)
50	0	.SetChoices("auto", "WKT", "EPSG", "PROJ");
51	0	}
52
53		/************************************************************************/
54		/* GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm() */
55		/************************************************************************/
56
57		GDALRasterIndexAlgorithm::GDALRasterIndexAlgorithm(
58		const std::string &name, const std::string &description,
59		const std::string &helpURL)
60	0	: GDALVectorOutputAbstractAlgorithm(name, description, helpURL)
61	0	{
62	0	}
63
64		/************************************************************************/
65		/* GDALRasterIndexAlgorithm::AddCommonOptions() */
66		/************************************************************************/
67
68		void GDALRasterIndexAlgorithm::AddCommonOptions()
69	0	{
70	0	AddArg("recursive", 0,
71	0	_("Whether input directories should be explored recursively."),
72	0	&m_recursive);
73	0	AddArg("filename-filter", 0,
74	0	_("Pattern that the filenames in input directories should follow "
75	0	"('*' and '?' wildcard)"),
76	0	&m_filenameFilter);
77	0	AddArg("min-pixel-size", 0,
78	0	_("Minimum pixel size in term of geospatial extent per pixel "
79	0	"(resolution) that a raster should have to be selected."),
80	0	&m_minPixelSize)
81	0	.SetMinValueExcluded(0);
82	0	AddArg("max-pixel-size", 0,
83	0	_("Maximum pixel size in term of geospatial extent per pixel "
84	0	"(resolution) that a raster should have to be selected."),
85	0	&m_maxPixelSize)
86	0	.SetMinValueExcluded(0);
87	0	AddArg("location-name", 0, _("Name of the field with the raster path"),
88	0	&m_locationName)
89	0	.SetDefault(m_locationName)
90	0	.SetMinCharCount(1);
91	0	AddAbsolutePathArg(
92	0	&m_writeAbsolutePaths,
93	0	_("Whether the path to the input datasets should be stored as an "
94	0	"absolute path"));
95	0	AddArg(GDAL_ARG_NAME_OUTPUT_CRS, 0, _("Output CRS"), &m_crs)
96	0	.SetIsCRSArg()
97	0	.AddHiddenAlias("dst-crs")
98	0	.AddHiddenAlias("t_srs");
99
100	0	{
101	0	auto &arg =
102	0	AddArg("metadata", 0, _("Add dataset metadata item"), &m_metadata)
103	0	.SetMetaVar("<KEY>=<VALUE>")
104	0	.SetPackedValuesAllowed(false);
105	0	arg.AddValidationAction([this, &arg]()
106	0	{ return ParseAndValidateKeyValue(arg); });
107	0	arg.AddHiddenAlias("mo");
108	0	}
109
110	0	AddArg("skip-errors", 0, _("Skip errors related to input datasets"),
111	0	&m_skipErrors);
112	0	AddArg("profile", 0, _("Profile of output dataset"), &m_profile)
113	0	.SetDefault(m_profile)
114	0	.SetChoices(PROFILE_NONE, PROFILE_STAC_GEOPARQUET);
115	0	AddArg("base-url", 0, _("Base URL for STAC-GeoParquet href"), &m_baseUrl);
116	0	AddArg("id-method", 0, _("How to derive STAC-GeoParquet 'id'"), &m_idMethod)
117	0	.SetDefault(m_idMethod)
118	0	.SetChoices(ID_METHOD_FILENAME, ID_METHOD_MD5, ID_METHOD_METADATA_ITEM);
119	0	AddArg("id-metadata-item", 0,
120	0	_("Name of metadata item used to set STAC-GeoParquet 'id'"),
121	0	&m_idMetadataItem)
122	0	.SetDefault(m_idMetadataItem)
123	0	.AddValidationAction(
124	0	[this]()
125	0	{
126	0	m_idMethod = ID_METHOD_METADATA_ITEM;
127	0	return true;
128	0	});
129
130	0	AddValidationAction(
131	0	[this]()
132	0	{
133	0	if (m_profile == PROFILE_STAC_GEOPARQUET)
134	0	{
135	0	if (!m_outputFormat.empty() &&
136	0	!EQUAL(m_outputFormat.c_str(), "Parquet"))
137	0	{
138	0	ReportError(CE_Failure, CPLE_NotSupported,
139	0	"STAC-GeoParquet profile is only compatible "
140	0	"with Parquet output format");
141	0	return false;
142	0	}
143	0	else if (m_outputFormat.empty() &&
144	0	!EQUAL(CPLGetExtensionSafe(
145	0	m_outputDataset.GetName().c_str())
146	0	.c_str(),
147	0	"parquet"))
148	0	{
149	0	ReportError(CE_Failure, CPLE_NotSupported,
150	0	"STAC-GeoParquet profile is only compatible "
151	0	"with Parquet output format");
152	0	return false;
153	0	}
154	0	m_outputFormat = "Parquet";
155
156	0	if (!m_crs.empty() && m_crs != "EPSG:4326")
157	0	{
158	0	OGRSpatialReference oSRS;
159	0	CPL_IGNORE_RET_VAL(oSRS.SetFromUserInput(m_crs.c_str()));
160	0	const char *pszCelestialBodyName =
161	0	oSRS.GetCelestialBodyName();
162		// STAC-GeoParquet requires EPSG:4326, but let be nice
163		// with planetary use cases and allow a non-Earth geographic CRS...
164	0	if (!(pszCelestialBodyName &&
165	0	!EQUAL(pszCelestialBodyName, "Earth") &&
166	0	oSRS.IsGeographic()))
167	0	{
168	0	ReportError(
169	0	CE_Failure, CPLE_NotSupported,
170	0	"STAC-GeoParquet profile is only compatible "
171	0	"with --output-crs=EPSG:4326");
172	0	return false;
173	0	}
174	0	}
175	0	if (m_crs.empty())
176	0	m_crs = "EPSG:4326";
177	0	}
178	0	return true;
179	0	});
180	0	}
181
182		/************************************************************************/
183		/* GDALRasterIndexAlgorithm::RunImpl() */
184		/************************************************************************/
185
186		bool GDALRasterIndexAlgorithm::RunImpl(GDALProgressFunc pfnProgress,
187		void *pProgressData)
188	0	{
189	0	CPLStringList aosSources;
190	0	for (auto &srcDS : m_inputDatasets)
191	0	{
192	0	CPLAssert(!srcDS.GetDatasetRef());
193	0	aosSources.push_back(srcDS.GetName());
194	0	}
195
196	0	auto setupRet = SetupOutputDataset();
197	0	if (!setupRet.outDS)
198	0	return false;
199
200	0	if (!SetDefaultOutputLayerNameIfNeeded(setupRet.outDS))
201	0	return false;
202
203	0	CPLStringList aosOptions;
204	0	aosOptions.push_back("--invoked-from-gdal-raster-index");
205
206	0	if (m_profile != PROFILE_NONE)
207	0	{
208	0	aosOptions.push_back("-profile");
209	0	aosOptions.push_back(m_profile);
210
211	0	if (!m_baseUrl.empty())
212	0	{
213	0	aosOptions.push_back("--base-url");
214	0	aosOptions.push_back(m_baseUrl);
215	0	}
216
217	0	aosOptions.push_back("--id-metadata-item");
218	0	aosOptions.push_back(m_idMetadataItem);
219
220	0	aosOptions.push_back("--id-method");
221	0	aosOptions.push_back(m_idMethod);
222	0	}
223
224	0	if (m_skipErrors)
225	0	{
226	0	aosOptions.push_back("-skip_errors");
227	0	}
228	0	if (m_recursive)
229	0	{
230	0	aosOptions.push_back("-recursive");
231	0	}
232	0	for (const std::string &s : m_filenameFilter)
233	0	{
234	0	aosOptions.push_back("-filename_filter");
235	0	aosOptions.push_back(s);
236	0	}
237	0	if (m_minPixelSize > 0)
238	0	{
239	0	aosOptions.push_back("-min_pixel_size");
240	0	aosOptions.push_back(CPLSPrintf("%.17g", m_minPixelSize));
241	0	}
242	0	if (m_maxPixelSize > 0)
243	0	{
244	0	aosOptions.push_back("-max_pixel_size");
245	0	aosOptions.push_back(CPLSPrintf("%.17g", m_maxPixelSize));
246	0	}
247
248	0	if (!m_outputLayerName.empty())
249	0	{
250	0	aosOptions.push_back("-lyr_name");
251	0	aosOptions.push_back(m_outputLayerName);
252	0	}
253
254	0	aosOptions.push_back("-tileindex");
255	0	aosOptions.push_back(m_locationName);
256
257	0	if (m_writeAbsolutePaths)
258	0	{
259	0	aosOptions.push_back("-write_absolute_path");
260	0	}
261	0	if (m_crs.empty())
262	0	{
263	0	if (m_sourceCrsName.empty())
264	0	aosOptions.push_back("-skip_different_projection");
265	0	}
266	0	else
267	0	{
268	0	aosOptions.push_back("-t_srs");
269	0	aosOptions.push_back(m_crs);
270	0	}
271	0	if (!m_sourceCrsName.empty())
272	0	{
273	0	aosOptions.push_back("-src_srs_name");
274	0	aosOptions.push_back(m_sourceCrsName);
275
276	0	aosOptions.push_back("-src_srs_format");
277	0	aosOptions.push_back(CPLString(m_sourceCrsFormat).toupper());
278	0	}
279
280	0	for (const std::string &s : m_metadata)
281	0	{
282	0	aosOptions.push_back("-mo");
283	0	aosOptions.push_back(s);
284	0	}
285
286	0	if (!AddExtraOptions(aosOptions))
287	0	return false;
288
289	0	std::unique_ptr<GDALTileIndexOptions, decltype(&GDALTileIndexOptionsFree)>
290	0	options(GDALTileIndexOptionsNew(aosOptions.List(), nullptr),
291	0	GDALTileIndexOptionsFree);
292
293	0	if (options)
294	0	{
295	0	GDALTileIndexOptionsSetProgress(options.get(), pfnProgress,
296	0	pProgressData);
297	0	}
298
299	0	const bool ret =
300	0	options && GDALTileIndexInternal(m_outputDataset.GetName().c_str(),
301	0	GDALDataset::ToHandle(setupRet.outDS),
302	0	OGRLayer::ToHandle(setupRet.layer),
303	0	aosSources.size(), aosSources.List(),
304	0	options.get(), nullptr) != nullptr;
305
306	0	if (ret && setupRet.newDS)
307	0	{
308	0	m_outputDataset.Set(std::move(setupRet.newDS));
309	0	}
310
311	0	return ret;
312	0	}
313
314		//! @endcond