swectral.roi_to_shp#

swectral.roi_to_shp(file_path, crs, name='', coordinates=None, roi_type='polygon', roi_list=None, return_path=True)[source]#

Write one or more polygon Regions of Interest (ROIs) to a Shapefile.

This function supports writing a single ROI via individual arguments or multiple ROIs via roi_list. When roi_list is provided, all single-ROI arguments are ignored.

Parameters:

file_pathstr

Path to the output ENVI XML ROI file.

crsstr or CRS

Coordinate reference system of the ROI(s).

Note: CRS must be provided. Non-georeferenced image may require additional alignment in GIS softwares.

namestr, optional

Name of the ROI when writing a single ROI. Ignored if roi_list is provided.

coordinateslist of list of tuple of 2 (float or int), optional

Vertex coordinate pairs defining the ROI geometry when writing a single ROI.

Structure:

[
    [ (x1, y1), (x2, y2), ..., (xn, yn), (x1, y1) ],  # Polygon 1
    [ (x1, y1), (x2, y2), ..., (xm, ym), (x1, y1) ],  # Polygon 2
    ...
]

Each inner list represents a polygon (for multipart geometries), and each tuple is a vertex coordinate.

Ignored if roi_list is provided.

roi_typestr, optional

Type of ROI to write.

Currently, only "polygon" is supported. This parameter has no effect and is reserved for future extensions.

Ignored if roi_list is provided.

roi_listlist of dict, optional

List of ROI definitions for writing multiple ROIs.

Each dictionary must contain the following keys:

{
    "name": str,
    "type": str,
    "coordinates": list of list of tuple of float
}

The coordinates entry represents one or more polygons as lists of vertex coordinate pairs.

return_pathbool, optional

If True, return the path to the generated ENVI XML ROI file.

Returns:

str or None: Path of the generated Shapefile if return_path is True; otherwise, None.

Return type:

Optional[str]

Examples

For single ROI with one polygon:

>>> roi_to_shp(
...     file_path="image_roi.shp",
...     crs="EPSG:4326",
...     name="roi1",
...     coordinates=[[(2.0, 2.0), (3.0, 2.0), (3.0, 3.0), (2.0, 3.0)]]
... )

For single ROI with multiple polygons:

>>> roi_to_shp(
...     file_path="image_roi.shp",
...     crs="EPSG:4326",
...     name="roi1",
...     coordinates=[
...             [(2.0, 2.0), (3.0, 2.0), (3.0, 3.0), (2.0, 3.0)],
...             [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0), (0.0, 0.0)],
...         ]
... )

For multiple ROis using roi_list:

>>> roi_to_shp(
...     file_path="image_roi.shp",
...     roi_list=[
...         {
...             "name": "test_roi_1",
...             "type": "polygon",
...             "coordinates": [[(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)]],
...         },
...         {
...             "name": "test_roi_2",
...             "type": "polygon",
...             "coordinates": [[(2.0, 2.0), (3.0, 2.0), (3.0, 3.0), (2.0, 3.0)]],
...         },
...     ]
... )