swectral.create_example_roi_xml#

swectral.create_example_roi_xml(xml_path, raster_width=10, raster_height=50, roi_count=10, roi_list=None, return_path=True, return_roi_list=False)#

Create a synthetic ENVI ROI XML file for demonstration or testing purposes.

Generates an ENVI-compatible ROI XML file containing a set of rectangular regions of interest (ROIs). Custom ROIs can be provided as a list of dictionaries.

By default, it creates 10 ROIs evenly distributed along the raster height.

Parameters:
xml_pathstr

Path to save the ROI XML file.

raster_widthint, optional

Width of the raster used to define ROI coordinates. Default is 10.

raster_heightint, optional

Height of the raster used to define ROI coordinates. Default is 50.

roi_countint, optional

Number of synthetic ROIs to generate if roi_list is not provided. Default is 10.

roi_listlist of dict, optional

Custom list of ROI dictionaries.

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
}

If None, synthetic ROIs are generated. Default is None.

return_pathbool, optional

If True, return the path of the generated XML file. Default is True.

return_roi_listbool, optional

If True, return the list of ROI dictionaries. Default is False.

Returns:
str, list of dict, (str, list of dict), or None

  • If return_path is True and return_roi_list is False: returns the XML file path (str).

  • If return_path is False and return_roi_list is True: returns the ROI list (list of dict).

  • If both are True: returns a tuple (path, roi_list).

  • If both are False: returns None.

Return type:

Union[str, list[dict], tuple[str, list[dict]], None]

Notes

Coordinates are defined in raster pixel units, and CRS is set to "none" by default. This method is also available as create_example_roi_xml.

Examples

Generate a default ROI XML file:

>>> create_test_roi_xml("test_rois.xml")

Generate a file with 5 ROIs for a raster of height 50:

>>> create_test_roi_xml("small_rois.xml", raster_height=50, roi_count=5)

Generate a file and also get the ROI list:

>>> xml_path, rois = create_test_roi_xml("example_rois.xml", return_roi_list=True)

Provide a custom ROI list:

>>> custom_rois = [
    ...     {"name": "ROI_1", "type": "polygon", "coordinates": [[(0, 0), (5, 0), (0, 5), (0, 0)]]}
    ... ]
>>> create_test_roi_xml("custom_rois.xml", roi_list=custom_rois)