tools: add --link and --out parameters for raster and vector files by tangelll · Pull Request #7182 · OSGeo/grass

tangelll · 2026-03-14T18:47:40Z

This pr open for this issue :#7176

Description:

There is a project in Grass Gsoc ideas list which name is Subcommand CLI for GRASS. I am being able to finish Add --link-raster=some/file.tiff which links (r.external) a raster file (same for vector and similarly for r.external.out).

How to do:

I tested the raster linking functionality using the ortho2010_t792_subset_20cm.tif file from the nc_spm_08_grass7 dataset, ensuring the map name matched the filename. For vector testing, I used the ne_110m_admin_0_countries dataset from Natural Earth as an external sample to verify the link process.

https://www.naturalearthdata.com/downloads/110m-cultural-vectors/110m-admin-0-countries/

To run my commands succesfuly you need to ensure that these files are in your workplaces.

Before Start

Before starting the test, ensure that you have copied your updated cli.py to the GRASS installation directory.

For me (macOS m4):

    cp cli.py /usr/local/grass85/etc/python/grass/app

To Test Image file

python3 -m grass.app run r.info --link-raster=ortho2010_t792_subset_20cm.tif map=ortho2010_t792_subset_20cm.1

Result

To Test Map file

 python3 -m grass.app run v.info --link-vector=/ne_110m_admin_0_countries/ne_110m_admin_0_countries.shp map=ne_110m_admin_0_countries

Result

OGR layer: ne_110m_admin_0_countries | 18:01 [260/653]
| OGR datasource: /Users/tangel/Downloads/ne_110m_admin_0_countries/ne_110m |

Feature type: polygon
Type of map: vector (level: 2)

Number of points: 0 Number of centroids: 288
Number of lines: 0 Number of boundaries: 289
Number of areas: 289 Number of islands: 289

Map is 3D: No
Number of dblinks: 1

Projection: x,y

N: 83.64513 S: -90
E: 180 W: -180

Digitization threshold: 0
Comment:

|

To Test Raster.out

You can change test folder name.

python3 -m grass.app run r.mapcalc "test_result = ortho2010_t792_subset_20cm.1" --link-raster=ortho2010_t792_subset_20cm.tif --out-raster=./test_salih

Result

Over-riding projection check
Reading band 1 of 3...
Link to raster map <ortho2010_t792_subset_20cm.1> created.
Reading band 2 of 3...
Link to raster map <ortho2010_t792_subset_20cm.2> created.
Reading band 3 of 3...
Link to raster map <ortho2010_t792_subset_20cm.3> created.
Imagery group <ortho2010_t792_subset_20cm> created
ortho2010_t792_subset_20cm.1
ortho2010_t792_subset_20cm.2
ortho2010_t792_subset_20cm.3
100%
➜ grass git:(subcommand_cli) ✗ cd test_salih
➜ test_salih git:(subcommand_cli) ✗ ls
test_result

To Test Vector.out

python3 -m grass.app run v.category input=ne_110m_admin_0_countries option=report 19:20 [5/1404]
t \                                                                                                                             
--link-vector=./ne_110m_admin_0_countries/ne_110m_admin_0_countries.shp \                                                       
--out-vector=./test_salih/test_result.gpkg

Result

Over-riding projection check 19:20 [1/1404]
Building topology for vector map ne_110m_admin_0_countries@PERMANENT...
Using external data format 'ESRI Shapefile' (feature type 'polygon')
Registering primitives...
577 primitives registered
10654 vertices registered
v.external complete. Link to vector map <ne_110m_admin_0_countries>
created.
Current output format for vectors: GPKG
Layer/table: 1/ne_110m_admin_0_countries
type count min max
point 0 0 0
line 0 0 0
boundary 289 0 176
centroid 0 0 0
area 0 0 0
face 0 0 0
kernel 0 0 0
all 289 0 176

Test For v.external under testsuite

Reading band -1 of 1...
ERROR 5: elevation.nc: GDALDataset::GetRasterBand(-1) - Illegal band #

ERROR: Selected band (-1) does not exist

Reading band 1 of 1...
Link to raster map <test_external_map> created.

ERROR 4: /Users/tangel/Works/grass/raster/r.external/testsuite/non_existent_file.tif: No such file or directory

Reading band 1 of 1...
Link to raster map <map_1> created.
Default region for this project updated
Region for the current mapset updated

Reading band 1 of 1...
Link to raster map <map_2> created.
Default region for this project updated
Region for the current mapset updated

Reading band 1 of 1...
Link to raster map <test_external_map> created.
Default region for this project updated
Region for the current mapset updated

Reading band 1 of 1...
Link to raster map <second_map> created.
Default region for this project updated
Region for the current mapset updated

Reading band 1 of 1...
Link to raster map <test_external_map> created.
Default region for this project updated
Region for the current mapset updated

No projection information available
Over-riding projection check
WARNING: Imagery group <test_external_map> already exists and will be
overwritten.
Reading band 1 of 5...
Link to raster map <test_external_map.1> created.
Reading band 2 of 5...
Link to raster map <test_external_map.2> created.
Reading band 3 of 5...
Link to raster map <test_external_map.3> created.
Reading band 4 of 5...
Link to raster map <test_external_map.4> created.
Reading band 5 of 5...
Link to raster map <test_external_map.5> created.
Imagery group <test_external_map> created

No projection information available
Over-riding projection check
Reading band 2 of 5...
Link to raster map <test_external_map> created.
Ok

tangelll · 2026-03-17T15:24:25Z

Hi @wenzeslaus,
I've been working on the Subcommand CLI for GRASS and would love to know if I'm heading in the right direction.

I have successfully implemented a 'one-step' execution flow where a user can link external data, run a module, and save the output externally in a single command.

It currently handles:

r.external / v.external linking before execution.

r.external.out / v.external.out for direct external output.

Does this align with the vision for CLI, or should I adjust the approach before moving further into the --region and import/export tasks?

wenzeslaus

This needs more testing and a deeper analysis. What happens when you use the command twice in a same project (with --project)? How are multiple parameters and parameter interactions handled?

Also, this completely misses tests which are explicitly mentioned in the GSoC idea.

wenzeslaus · 2026-03-18T03:17:09Z

python/grass/app/cli.py

+    create_parser.add_argument(
+        "--link-raster",
+        action="append",
+        help="link a raster map to the project (can be used multiple times)",
+    )


What would be the use case for these in a workflow?

wenzeslaus · 2026-03-18T03:18:28Z

python/grass/app/cli.py

+    run_subparser.add_argument(
+        "--link-raster",
+        type=str,
+        nargs="+",


This eats the "named arguments" unless used with =. Needs more config.

tangelll · 2026-03-29T15:15:41Z

I would like to confirm if my testing methodology is on the right track. I noticed that there is currently no testsuite folder under v.external. Should I go ahead and create a new testsuite directory and add my test files there? Once I have your approval on this structure, I will proceed with the rest of the tests.

echoix · 2026-03-29T18:34:56Z

Yes, you can create a testsuite folder for a gunittest-based test, or test folder for pytest-based test

tangelll added 3 commits March 14, 2026 18:03

add subcommand for --link-raster

1e4fd40

add --link-raster

0efb366

add subcommand for link raster

310a46a

github-actions bot added Python Related code is in Python libraries labels Mar 14, 2026

tangelll changed the title ~~add subcommand for --link-raster~~ r.external: add subcommand for vector, raster file and r.external.out Mar 14, 2026

tangelll changed the title ~~r.external: add subcommand for vector, raster file and r.external.out~~ cli: add --link and --out parameters for raster and vector files to 'run' tool Mar 14, 2026

tangelll changed the title ~~cli: add --link and --out parameters for raster and vector files to 'run' tool~~ tools: add --link and --out parameters for raster and vector files Mar 15, 2026

vector and raster out implemented

8184e33

Merge branch 'main' into subcommand_cli

a66b9d8

wenzeslaus requested changes Mar 18, 2026

View reviewed changes

tangelll added 2 commits March 29, 2026 18:06

Code Tests are added.

3063be1

test are added.

8f0e47b

github-actions bot added raster Related to raster data processing module tests Related to Test Suite labels Mar 29, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

tools: add --link and --out parameters for raster and vector files#7182

tools: add --link and --out parameters for raster and vector files#7182
tangelll wants to merge 7 commits intoOSGeo:mainfrom
tangelll:subcommand_cli

tangelll commented Mar 14, 2026 •

edited

Loading

Uh oh!

tangelll commented Mar 17, 2026 •

edited

Loading

Uh oh!

wenzeslaus left a comment

Uh oh!

wenzeslaus Mar 18, 2026

Uh oh!

wenzeslaus Mar 18, 2026

Uh oh!

tangelll commented Mar 29, 2026 •

edited

Loading

Uh oh!

echoix commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

tangelll commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description:

How to do:

Before Start

To Test Image file

Result

To Test Map file

Result

To Test Raster.out

Result

To Test Vector.out

Result

Test For v.external under testsuite

Uh oh!

tangelll commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wenzeslaus left a comment

Choose a reason for hiding this comment

Uh oh!

wenzeslaus Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

wenzeslaus Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

tangelll commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

echoix commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tangelll commented Mar 14, 2026 •

edited

Loading

tangelll commented Mar 17, 2026 •

edited

Loading

tangelll commented Mar 29, 2026 •

edited

Loading