i.landsat.qa
Reclassifies Landsat QA band according to acceptable pixel quality as defined by the user.
i.landsat.qa [output=name] [dataset=string] [designated_fill=string] [cloud=string] [cloud_confidence=string [,string,...]] [cloud_shadow_confidence=string [,string,...]] [snow_ice_confidence=string [,string,...]] [cirrus_confidence=string [,string,...]] [dilated_cloud=string] [snow=string] [clear=string] [water=string] [terrain_occlusion=string] [radiometric_saturation=string [,string,...]] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
i.landsat.qa designated_fill=string
grass.script.run_command("i.landsat.qa", output=None, dataset="landsat_8_c1", designated_fill=None, cloud=None, cloud_confidence=None, cloud_shadow_confidence=None, snow_ice_confidence=None, cirrus_confidence=None, dilated_cloud=None, snow=None, clear=None, water=None, terrain_occlusion=None, radiometric_saturation=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("i.landsat.qa", designated_fill="string")
Parameters
output=name
Output file with reclass rules
dataset=string
Landsat dataset to search for
Allowed values: landsat_tm_c1, landsat_etm_c1, landsat_8_c1, landsat_tm_c2_l1, landsat_tm_c2_l2, landsat_etm_c2_l1, landsat_etm_c2_l2, landsat_ot_c2_l1, landsat_ot_c2_l2
Default: landsat_8_c1
designated_fill=string
Unacceptable conditions for Designated Fill
Allowed values: No, Yes
cloud=string
Unacceptable conditions for Clouds
Allowed values: No, Yes
cloud_confidence=string [,string,...]
Unacceptable conditions for Cloud confidence
Allowed values: Not Determined, Low, Medium, High
cloud_shadow_confidence=string [,string,...]
Unacceptable conditions for Cloud Shaddow Confidence
Allowed values: Not Determined, Low, Medium, High
snow_ice_confidence=string [,string,...]
Unacceptable conditions for Snow/Ice Confidence
Allowed values: Not Determined, Low, Medium, High
cirrus_confidence=string [,string,...]
Unacceptable conditions for Cirrus Confidence
Allowed values: Not Determined, Low, Medium, High
dilated_cloud=string
Unacceptable conditions for Pixels with Dilated Clouds (only collection 2)
Allowed values: No, Yes
snow=string
Unacceptable conditions for Snow Pixels (only collection 2)
Allowed values: No, Yes
clear=string
Unacceptable conditions for Clear Pixels (only collection 2)
Allowed values: No, Yes
water=string
Unacceptable conditions for Water Pixels (only collection 2)
Allowed values: No, Yes
terrain_occlusion=string
Unacceptable conditions for Terrain Occlusion / Dropped Pixels (only collection 1)
Allowed values: No, Yes
radiometric_saturation=string [,string,...]
Unacceptable conditions for Radiometric Saturation (only collection 1)
Allowed values: Not Determined, Low, Medium, High
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
output : str, optional
Output file with reclass rules
Used as: output, file, name
dataset : str, optional
Landsat dataset to search for
Allowed values: landsat_tm_c1, landsat_etm_c1, landsat_8_c1, landsat_tm_c2_l1, landsat_tm_c2_l2, landsat_etm_c2_l1, landsat_etm_c2_l2, landsat_ot_c2_l1, landsat_ot_c2_l2
Default: landsat_8_c1
designated_fill : str, optional
Unacceptable conditions for Designated Fill
Allowed values: No, Yes
cloud : str, optional
Unacceptable conditions for Clouds
Allowed values: No, Yes
cloud_confidence : str | list[str], optional
Unacceptable conditions for Cloud confidence
Allowed values: Not Determined, Low, Medium, High
cloud_shadow_confidence : str | list[str], optional
Unacceptable conditions for Cloud Shaddow Confidence
Allowed values: Not Determined, Low, Medium, High
snow_ice_confidence : str | list[str], optional
Unacceptable conditions for Snow/Ice Confidence
Allowed values: Not Determined, Low, Medium, High
cirrus_confidence : str | list[str], optional
Unacceptable conditions for Cirrus Confidence
Allowed values: Not Determined, Low, Medium, High
dilated_cloud : str, optional
Unacceptable conditions for Pixels with Dilated Clouds (only collection 2)
Allowed values: No, Yes
snow : str, optional
Unacceptable conditions for Snow Pixels (only collection 2)
Allowed values: No, Yes
clear : str, optional
Unacceptable conditions for Clear Pixels (only collection 2)
Allowed values: No, Yes
water : str, optional
Unacceptable conditions for Water Pixels (only collection 2)
Allowed values: No, Yes
terrain_occlusion : str, optional
Unacceptable conditions for Terrain Occlusion / Dropped Pixels (only collection 1)
Allowed values: No, Yes
radiometric_saturation : str | list[str], optional
Unacceptable conditions for Radiometric Saturation (only collection 1)
Allowed values: Not Determined, Low, Medium, High
overwrite: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
Removing unreliable pixels is a fundamental and one of the first steps in remote sensing. Landsat imagery provides a Quality Assessment (QA) band which can be used for this purpose.
The i.landsat.qa module generates reclassification rule files which can be used in r.reclass for filtering the QA band according to pixel quality characteristics the user defines as unacceptable. It works with both Collection 1 and Collection 2 data from Landsat 8 OLI/TIRS, 4-7 TM/ETM+. The dataset the QA band belongs to is specified like in i.landsat.download.
Values defined as unacceptable for a given condition will be set to NULL in the output raster map. All other values will be set to 1.
The Quality Assessment (QA) band from Landsat contains 16bit integer values that represent "bit-packed combinations of surface, atmosphere, and sensor conditions that can affect the overall usefulness of a given pixel".
The following quality relevant conditions are represented as "single bits" in the Landsat QA band:
| Condition | Collection |
| Designated Fill | 1,2 |
| Dilated Cloud | 2 |
| Terrain Occlusion / Dropped Pixels | 1 |
| Cloud | 1,2 |
| Cirrus | 2 |
| Cloud Shadow | 2 |
| Snow | 2 |
| Clear | 2 |
| Water | 2 |
Possible choices for the "single bits" are:
| Value | Description | Bit representation |
| No | This condition does not exist | 0 |
| Yes | This condition exists | 1 |
The following quality relevant conditions are represented as "double bits" in the Landsat QA band:
| Condition | Collection |
| Radiometric saturation | 2 |
| Cloud Confidence | 1,2 |
| Cloud Shadow Confidence | 1,2 |
| Snow/Ice Confidence | 1,2 |
| Cirrus Confidence | 1,2 |
Possible choices for the "double bits" are:
| Value | Description | Bit representation |
| Not Determined | Algorithm did not determine the status of this condition | 00 |
| Low | Algorithm has low to no confidence that this condition exists (0-33 percent confidence) | 01 |
| Medium | Algorithm has medium confidence that this condition exists (34-66 percent confidence) | 10 |
| High | Algorithm has high confidence that this condition exists (67-100 percent confidence) | 11 |
NOTES
The Landsat Quality Assessment band is an artificial band which represents an analysis based on defined algorithms. The USGS provides the users with the following note on how the QA band should be used:
"Rigorous science applications seeking to optimize the value of pixels used in a study will find QA bits useful as a first level indicator of certain conditions. Otherwise, users are advised that this file contains information that can be easily misinterpreted and it is not recommended for general use."
EXAMPLE
# Create a cloud mask:
i.landsat.qa --overwrite --verbose cloud_confidence="Medium,High" \
dataset="landsat_ot_c2_l2" \
output=./Cloud_Mask_rules.txt
r.reclass input=LC81980182015183LGN00_BQA \
output=LC81980182015183LGN00_Cloud_Mask rules=./Cloud_Mask_rules.txt
# Create a water mask (only available for collection 2):
i.landsat.qa --overwrite --verbose water="Yes" \
dataset="landsat_ot_c2_l2" \
output=./Water_Mask_rules.txt
r.reclass input=LC81980182015183LGN00_BQA \
output=LC81980182015183LGN00_Water_Mask rules=./Water_Mask_rules.txt
SEE ALSO
r.reclass, i.modis.qc, r.bitpattern, i.landsat i.landsat8.swlst
REFERENCES
Landsat Collection 1 Level 1 Quality Assessment bands Landsat Collection 2 Level 1 Quality Assessment bands
AUTHOR
Stefan Blumentrath, Norwegian Institute for Nature Research, Oslo (Norway)
SOURCE CODE
Available at: i.landsat.qa source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819