swectral.roi_to_envi#

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

Write one or more polygon Regions of Interest (ROIs) to an ENVI XML ROI file.

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.

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.

crsstr or CRS, optional

Coordinate reference system of the ROI.

Use "none" for image-space coordinates (ENVI default).

Ignored if roi_list is provided.

colortuple of int, optional

RGB color of the ROI specified as (R, G, B), where each value is in the range 0–255.

If None, a random color is assigned. Default is None.

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,
    "crs": str or CRS,
    "color": tuple of int or None,
    "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 ENVI XML ROI file if return_path is True; otherwise, None.

Return type:

Optional[str]

Notes

In ENVI, polygons, rectangles, and ellipses are all represented internally as polygon geometries. This function therefore writes all supported ROI types as polygons in the ENVI XML schema.

Examples

For single ROI with one polygon:

>>> roi_to_envi(
...     file_path="image_roi.xml",
...     name="roi1",
...     coordinates=[[(2.0, 2.0), (3.0, 2.0), (3.0, 3.0), (2.0, 3.0)]],
...     crs="EPSG:4326",
...     color=(255, 0, 0),
... )

For single ROI with multiple polygons:

>>> roi_to_envi(
...     file_path="image_roi.xml",
...     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)],
...         ],
...     crs="EPSG:4326",
...     color=(255, 0, 0)
... )

For multiple ROis using roi_list:

>>> roi_to_envi(
...     file_path="image_roi.xml",
...     roi_list=[
...         {
...             "name": "test_roi_1",
...             "crs": "EPSG:4326",
...             "color": (255, 0, 0),
...             "type": "polygon",
...             "coordinates": [[(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)]],
...         },
...         {
...             "name": "test_roi_2",
...             "crs": "EPSG:3857",
...             "color": (0, 255, 0),
...             "type": "polygon",
...             "coordinates": [[(2.0, 2.0), (3.0, 2.0), (3.0, 3.0), (2.0, 3.0)]],
...         },
...     ]
... )