Skip to content

grass.experimental: Add NumPy arrays IO to Tools #5878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 28 commits into
base: main
Choose a base branch
from

Conversation

wenzeslaus
Copy link
Member

@wenzeslaus wenzeslaus commented Jun 11, 2025

This is adding NumPy array as input and output to tools when called through the Tools object.

This is building on top of Tools class addition in #2923 (which is not merged yet), so for now it includes changes also from that PR. The big picture is also discussed in #5830.

While this can't be merged now, we can discuss the specific aspects of NumPy array handling here. My focus with this PR is to create a good API which can be used in various contexts and is useful as is. However, the specifics of the implementation, especially performance are secondary issues for me in this PR.

Main functionality

In an existing session (e.g., in a GRASS tool):

tools = Tools()
tools.g_region(rows=2, cols=3)
slope = tools.r_slope_aspect(elevation=np.ones((2, 3)), slope=np.ndarray)

In a Python script:

gs.create_project("project1")
with gs.setup.init("project1") as session:
    tools = Tools(session=session)
    tools.g_region(rows=2, cols=3)
    slope = tools.r_slope_aspect(elevation=np.ones((2, 3)), slope=np.ndarray)

For tests

Writing pytests and testing the outputs is greatly simplified without introducing additional functionality (not saying that we should not evaluate what more we need for pytest, but we can do it in light of this):

def test_slope(xy_session):
    tools = Tools(session=xy_session)
    tools.g_region(rows=2, cols=3)
    slope = tools.r_slope_aspect(elevation=np.ones((2, 3)), slope=np.ndarray)
    assert slope.shape == (2, 3)
    assert np.all(slope == np.full((2, 3), 0))

wenzeslaus and others added 28 commits June 3, 2023 23:57
This adds a Tools class which allows to access GRASS tools (modules) to be accessed using methods. Once an instance is created, calling a tool is calling a function (method) similarly to grass.jupyter.Map. Unlike grass.script, this does not require generic function name and unlike grass.pygrass module shortcuts, this does not require special objects to mimic the module families.

Outputs are handled through a returned object which is result of automatic capture of outputs and can do conversions from known formats using properties.

Usage example is in the _test() function in the file.

The code is included under new grass.experimental package which allows merging the code even when further breaking changes are anticipated.
…needs to be improved there). Allow usage through attributes, run with run_command syntax, and subprocess-like execution.
…est a tool when there is a close match for the name.
…tool in XY project, so useful only for things like g.extension or m.proj, but, with a significant workaround for argparse --help, it can do --help for a tool.
@wenzeslaus wenzeslaus added enhancement New feature or request Python Related code is in Python labels Jun 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request libraries Python Related code is in Python tests Related to Test Suite
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants