Resolves GlacioHack/xdem#602

Description

This PR introduces the functionality for handling a Region of Interest (ROI) when loading raster data. Specifically, it ensures that rasters can be loaded with a specific subset of their data, as defined by a ROI. This functionality is available during the raster initialization. The ROI can be either pixel-based or georeferenced.

Changes

1. New roi parameter in the Raster class constructor:

• The roiparameter is introduced to specify the region of interest when loading a raster. It is a dictionary with the keys:
  • x, y, w, and h if pixel-based (where (x, y) top-left corner coordinates and (w, h) the dimensions (width, height) in pixels).
  • left, bottom, right, top and optional crs (defaults to EPSG:4326) if georeferenced, representing the bounding box of the region to load.
• The parameter is used in the Raster class to crop the raster data during initialization. If provided, the data will be sliced accordingly, while also adjusting the transform and metadata to match the cropped area.

2. New convert_roi method:

• Converts the ROI from georeferenced coordinates (e.g., latitude/longitude) or pixel-based coordinates into the appropriate coordinate system and pixel indices for the target raster.
• Ensures the ROI is correctly aligned with the raster's CRS and verifies that the resulting pixel indices are valid and within the raster dimensions.
• Includes validation logic to ensure the converted ROI is well-formed, i.e., the bounding box is valid, and the ROI fits within the raster bounds without inverting the top/bottom or left/right limits.

3. _load_rio function modification:

• The _load_rio function now supports the roi parameter to load a specific subset of raster data directly from the disk.
• It handles the creation of a Window for reading the data in the specified region, ensuring that only the relevant part of the raster is loaded into memory.

4. Support for ROI during raster creation:

• The from_array method now supports an optional roiparameter. This allows users to define a ROI when creating a raster from an in-memory numpy array.
• When a ROI is provided, the data is sliced accordingly before the raster is created.

Tests

• New test test_raster_with_roi: This test verifies the correct behavior when loading raster data with a specified ROI. It checks that the raster is properly cropped and ensures the output data matches expectations when applying either a georeferenced or pixel-based ROI. This ensures the convert_roi method functions as intended in real-world use cases.
• Additional tests in test_init and test_from_array: These tests have been extended to validate behavior when a ROI is provided but the raster is initialized without a file path. The tests ensure that the ROI is correctly handled when working with arrays directly, confirming the method's compatibility with non-file-based rasters.

Documentation

• The section crop in the raster documentation has been updated with the possibility to pass a ROI in parameter and crop the raster during initialization.

Example

# Create a raster with a region of interest

# ROI pixel-based
raster = Raster('path/to/raster.tif', load_data=True, roi={'x': 50, 'y': 100, 'w': 400, 'h': 300})

# ROI georeferenced
raster = Raster('path/to/raster.tif', load_data=True, roi={'left': 0, 'right': 1, 'bottom': 43, 'top': 44})