To use IRIS, you need to define a project file in JSON or YAML format. A full-working example can be found here. The following will outline each of the fields one can use to change the behaviour of IRIS. If fields are not explicitly given in a project's configuration file, then they will take the values found in the default configuration file.
Optional name for this project.
Example:
"name": "cloud-segmentation"
Set the port which IRIS is served on. Defaults to 5000. Example:
"port": 6060
Set the host IP address for IRIS. The default value 127.0.0.1 means IRIS will only be visible on the local machine. If you want to expose IRIS publicly as a web application, we recommend setting the host to 0.0.0.0 and adjusting your router / consulting with your network administrators accordingly. Example:
"host": 0.0.0.0
A dictionary which defines the inputs.
Example:
"images": {
"path": "images/{id}/image.tif",
"shape": [512, 512],
"thumbnails": "images/{id}/thumbnail.png",
"metadata": "images/{id}/metadata.json"
}
This hold the input path to the images. Can be either a string containing an existing path with the placeholder {id} or a dictionary of paths with the placeholder {id} (see examples below). The placeholder will be replaced by the unique id of the current image. IRIS can load standard image formats (like png or tif), theoretically all kind of files that can be opened by GDAL/rasterio (such as geotiff or vrt) and numpy files (npy). The arrays inside the numpy files should have the shape HxWxC.
Example:
When you have one folder images containing your images in tif format:
"path": "images/{id}.tif"
When you have one folder images containing subfolders with your images in tif format:
"path": "images/{id}/image.tif"
When you have your data distributed over multiple files (e.g. coming from Sentinel-1 and Sentinel-2), you can use a dictionary for each file type. The keys of the dictionary are file identifiers which are important for the views configuration.
"path": {
"Sentinel1": "images/{id}/S1.tif",
"Sentinel2": "images/{id}/S2.tif"
}
The shape of the images. Must be a list of width and height.
"shape": [512, 512]
Optional thumbnail files for the images. Path must contain a placeholder {id}. If you cannot provide any thumbnail, just leave it out or set it to false.
Example:
"thumbnails": "thumbnails/{id}.png"
Optional metadata for the images. Path must contain a placeholder {id}. Metadata files can be in json, yaml or another text file format. json and yaml files will be parsed and made accessible via the GUI. If the metadata contains the key location with a list of two floats (longitude and latitude), it can be used for a bingmap view. If you cannot provide any metadata, just leave it out or set it to false.
Example:
"metadata": "metadata/{id}.json"
Example for metadata file:
{
"spacecraft_id": "Sentinel2",
"scene_id": "coast",
"location": [-26.3981, 113.3077],
"resolution": 20.0
}
This is a list of classes that you want to allow the user to label. Each class is represented as a dictionary with the following keys:
- *name:* Name of the class
- *description:* Further description which explains the user more about the class (e.g. why is it different from another class, etc.)
- *colour:* Colour for this class. Must be a list of 4 integers (RGBA) from 0 to 255.
- *user_colour (optional):* Colour for this class when user mask is activated in the interface. Useful for background classes which are normally transparent.
Example:
"classes": [
{
"name": "Clear",
"description": "All clear pixels.",
"colour": [255,255,255,0],
"user_colour": [0,255,255,70]
},
{
"name": "Cloud",
"description": "All cloudy pixels.",
"colour": [255,255,0,70]
}
]
Since this app was developed for multi-spectral satellite data (i.e. images with more than just three channels), you can decide how to present the images to the user. This option must be a dictionary where each key is the name of the view and the value another dictionary containing properties for the view:
- *description:* Further description which explains what the user can see in this view.
- *type:* Can be either `bingmap` or `image`.
- *data:* Can be either one string (monochrome image) or a list of three strings (rgb image). Each string must contain an expression that returns a valid band array. It can contain mathematical expressions, band combinations or calls of specific functions like `edges` or `superpixels`. One refers to the bands by using variable names starting with `$B`, e.g. `$B1` for the first band of the image file. If you set `image:path` to a dictionary, you need the file identifiers as prefix, i.e. `$FileIdentifier.B1` (e.g. `$Sentinel2.B1`).
- *cmap:* If `data` contains only one string (monochrome image), you can set a matplotlib colormap name here to render that image.
- *clip:* By default, bands are stretched between 0 and 1, relative to their minimum and maximum values. By setting a value for clip, you control the percentile of pixels that are saturated at 0 and 1, which can be helpful if there are some extreme pixel values that reduce the contrast in other parts of the image.
- *vmin/vmax* If you know the precise values you would like to clip the pixel values to, (rather than a percentile), then you can specify these with vmin and/or vmax. This cannot be used for the same view as `clip`.
Example:
"views": {
"Cirrus": {
"description": "Cirrus and high clouds are red.",
"type": "image",
"data": "$Sentinel2.B11**0.8*5",
"cmap": "jet"
},
"Cirrus-Edges": {
"description": "Edges in the cirrus band",
"type": "image",
"data": "edges($Sentinel2.B11**0.8*5)*1.5",
"cmap": "gray"
},
"RGB": {
"description": "Normal RGB image.",
"type": "image",
"data": ["$Sentinel2.B5", "$Sentinel2.B3", "$Sentinel2.B2"]
},
"Sentinel-1": {
"description": "RGB of VH, VV and VH-VV.",
"type": "image",
"data": ["$Sentinel1.B1", "$Sentinel1.B2", "$Sentinel1.B1-$Sentinel1.B2"]
},
"Superpixels": {
"description": "Superpixels in the panchromatic bands",
"type": "image",
"data": "superpixels($Sentinel2.B2+$Sentinel2.B3+$Sentinel2.B4, sigma=4, min_size=100)",
"cmap": "jet"
},
"Bing": {
"description": "Aerial Imagery",
"type": "bingmap"
}
}
Views are displayed in groups. In the GUI of IRIS, you will be able to switch between different groups quickly.
The group default must always be set, further groups are optional.
"view_groups": {
"default": ["Cirrus", "RGB", "Bing"],
"clouds": ["Cirrus"],
"radar": ["Sentinel1"]
}
A dictionary which defines the parameters for the segmentation mode.
This directory will contain the mask files from the segmentation. Four different mask formats are allowed: npy, tif, png or jpeg.
Example:
This will create a folder next to the project file called masks containing the mask files in png format.
"path": "masks/{id}.png"
The encodings of the final masks. Can be integer, binary, rgb or rgba.
Note: not all mask formats support all encodings.
Example:
"mask_encoding": "rgb"
In case you don't want to allow the user to label the complete image, you can limit the segmentation area.
Example:
"mask_area": [100, 100, 400, 400]
Defines how to measure the score achieved by the user for each mask. Can be
f1, jaccard or accuracy. Default is f1
Example:
"score": "f1"