remove image tool folder to simplify installation procedure, and add more comments

Author: SuYe99

prepare_ard.log

@@ -0,0 +1 @@
+INFO:__main__:AutoPrepareDataARD starts: 2024-11-22 03:01:34

requirements/runtime.txt

@@ -28,10 +28,5 @@ astropy>=5.1       ; python_version < '3.11' and python_version >= '3.10'    # P
 astropy>=5.1       ; python_version < '3.10' and python_version >= '3.9'     # Python 3.9
 astropy>=5.1       ; python_version < '3.9'  and python_version >= '3.8'     # Python 3.8
 
-
-# rasterio>=1.3
-
-# Note: 
-# gdal is also required, but needs to be installed separately 
-# due to depending on an external package index.
-# see gdal.txt
+rasterio>=1.4  ; python_version >= '3.9'
+rasterio>=1.3  ; python_version < '3.9'  and python_version >= '3.8'

src/cxx/test.py

@@ -10,6 +10,7 @@
 from .common import SccdOutput
 from ._param_validation import (
     validate_parameter_constraints,
+    Integral,
     Interval,
     Real,
     check_consistent_length,
@@ -402,8 +403,8 @@ def sccd_detect(
     b_pinpoint: bool, output pinpoint break where pinpoint is an overdetection of break using conse =3
                         and threshold = gate_tcg, which are used to simulate the situation of NRT scenario and
                         for training a machine-learning model
-    gate_pcg: the gate change probability threshold for defining anomaly
-    state_intervaldays: the day interval for output states (only b_output_state is True)
+    gate_pcg: the gate change probability threshold for defining spectral anomaly (for the follow-up supervised approach)
+    state_intervaldays: the day interval for output states
     b_fitting_coefs: True indicates using curve fitting to get global harmonic coefficients, otherwise use the local coefficients 
     Returns
     ----------

src/python/pycold/colds.py

@@ -2,11 +2,11 @@
 from collections import namedtuple
 from dataclasses import dataclass, field
 
-DEFAULT_CONSE = 8
-NRT_BAND = 6
-SCCD_NUM_C = 6
-TOTAL_BAND_FLEX = 10
-TOTAL_BAND_FLEX_NRT = 8
+SCCD_CONSE_OUTPUT = 8  # the default outputted observation number once S-CCD detects breakpoint or pinpoint, note it is not the conse for identifying breakpoints/pinpoints 
+NRT_BAND = 6    # the default S-CCD band number
+SCCD_NUM_C = 6  # the S-CCD harmonic model coefficient number
+TOTAL_BAND_FLEX = 10    # the maximum band input for flexible mode of COLD
+TOTAL_BAND_FLEX_NRT = 8 # the maximum band input for flexible mode of S-CCD
 
 reccg_dt = np.dtype(
     [
@@ -15,29 +15,40 @@
         ("t_break", np.int32),  # time when the first break (change) is observed
         ("pos", np.int32),  # the location of each time series model
         ("num_obs", np.int32),  # the number of "good" observations used for model estimation
-        # the quality of the model estimation (what model is used, what process is used)
-        ("category", np.short),
-        # the probability of a pixel that have undergone change (between 0 and 100)
-        ("change_prob", np.short),
-        # coefficients for each time series model for each spectral band
-        ("coefs", np.float32, (7, 8)),
-        ("rmse", np.float32, 7),  # RMSE for each time series model for each spectral band
-        ("magnitude", np.float32, 7),
+        ("category", np.short), # the quality of the model estimation as a two-digit number (what model is used, what process is used)
+            # first digit:
+            #     0: normal model (no change)
+            #     1: change at the beginning of time series model
+            #     2: change at the end of time series model
+            #     3: disturbance change in the middle
+            #     4: fmask fail scenario
+            #     5: permanent snow scenario
+            #     6: outside user mask
+            # second digit:
+            #     1: model has only constant term
+            #     4: model has 4 coefs
+            #     6: model has 6 coefs
+            #     8: model has 8 coefs*/
+            # for example, 8 represents "normal model + 8 coefficients"
+        ("change_prob", np.short), # the probability of a pixel that have undergone change (between 0 and 100)
+        ("coefs", np.float32, (7, 8)), # coefficients for each time series model for seven spectral band, seven bands follow the order of "blue, green, red, nir, swir1, swir2, thermal"
+                                       # seven row has 8 coefficients representing a 'annual-semiannual-trimode' harmonic model
+        ("rmse", np.float32, 7),  # RMSE for each time series model for each seven band
+        ("magnitude", np.float32, 7), # the magnitude of difference between model prediction and observation for each spectral band
     ]
-)  # the magnitude of change difference between model prediction
-# and observation for each spectral band)
+)  
 
 
 SccdOutput = namedtuple("SccdOutput", "position rec_cg min_rmse nrt_mode nrt_model nrt_queue")
 
 sccd_dt = np.dtype(
     [
-        ("t_start", np.int32),
-        ("t_break", np.int32),
-        ("num_obs", np.int32),
-        ("coefs", np.float32, (NRT_BAND, SCCD_NUM_C)),
-        ("rmse", np.float32, NRT_BAND),
-        ("magnitude", np.float32, NRT_BAND),
+        ("t_start", np.int32), # ordenal date for the start of the time-series segment
+        ("t_break", np.int32), # ordenal date for the break of the time-series segment
+        ("num_obs", np.int32),  # the number of "good" observations used for model estimation
+        ("coefs", np.float32, (NRT_BAND, SCCD_NUM_C)), # coefficients for each time series model for six spectral band 
+        ("rmse", np.float32, NRT_BAND),    # RMSE for each time series model for each seven band
+        ("magnitude", np.float32, NRT_BAND), # the magnitude of difference between model prediction and observation for each spectral band
     ],
     align=True,
 )
@@ -46,16 +57,16 @@
 
 nrtmodel_dt = np.dtype(
     [
-        ("t_start_since1982", np.short),
-        ("num_obs", np.short),
-        ("obs", np.short, (NRT_BAND, DEFAULT_CONSE)),
-        ("obs_date_since1982", np.short, DEFAULT_CONSE),
-        ("covariance", np.float32, (NRT_BAND, 36)),
-        ("nrt_coefs", np.float32, (NRT_BAND, SCCD_NUM_C)),
-        ("H", np.float32, NRT_BAND),
-        ("rmse_sum", np.uint32, NRT_BAND),
-        ("norm_cm", np.short),
-        ("cm_angle", np.short),
+        ("t_start_since1982", np.short),    # the date number since 1982-1-1 for the start of the time-series segment, equal to ordinal date + 723546 
+        ("num_obs", np.short), # the number of "good" observations used for model estimation
+        ("obs", np.short, (NRT_BAND, SCCD_CONSE_OUTPUT)),  # eight multispectral observations at tail (6 * 8)
+        ("obs_date_since1982", np.short, SCCD_CONSE_OUTPUT),   # eight observation dates (counted since 1982-1-1) at tail (6 * 8)
+        ("covariance", np.float32, (NRT_BAND, 36)),  # covariance matrix for six bands (6 * 36)
+        ("nrt_coefs", np.float32, (NRT_BAND, SCCD_NUM_C)), # the current nrt_coefs (6 * 6)
+        ("H", np.float32, NRT_BAND),    # the cobservation uncertainties (6 * 1)
+        ("rmse_sum", np.uint32, NRT_BAND), # the sum of RMSE (6 * 1)
+        ("norm_cm", np.short), # the normalized change magnitude
+        ("cm_angle", np.short), # the included change angle
         ("conse_last", np.ubyte),
     ],
     align=True,
@@ -66,10 +77,10 @@
     [
         ("t_break", np.int32),
         ("coefs", np.float32, (NRT_BAND, SCCD_NUM_C)),
-        ("obs", np.short, (NRT_BAND, DEFAULT_CONSE)),
-        ("obs_date_since1982", np.short, DEFAULT_CONSE),
-        ("norm_cm", np.short, DEFAULT_CONSE),
-        ("cm_angle", np.short, DEFAULT_CONSE),
+        ("obs", np.short, (NRT_BAND, SCCD_CONSE_OUTPUT)),
+        ("obs_date_since1982", np.short, SCCD_CONSE_OUTPUT),
+        ("norm_cm", np.short, SCCD_CONSE_OUTPUT),
+        ("cm_angle", np.short, SCCD_CONSE_OUTPUT),
     ],
     align=True,
 )
@@ -82,12 +93,9 @@
         ("t_break", np.int32),  # time when the first break (change) is observed
         ("pos", np.int32),  # the location of each time series model
         ("num_obs", np.int32),  # the number of "good" observations used for model estimation
-        # the quality of the model estimation (what model is used, what process is used)
-        ("category", np.short),
-        # the probability of a pixel that have undergone change (between 0 and 100)
-        ("change_prob", np.short),
-        # coefficients for each time series model for each spectral band
-        ("coefs", np.float32, (TOTAL_BAND_FLEX, 8)),
+        ("category", np.short),  # the quality of the model estimation (what model is used, what process is used)
+        ("change_prob", np.short), # the probability of a pixel that have undergone change (between 0 and 100)
+        ("coefs", np.float32, (TOTAL_BAND_FLEX, 8)), # coefficients for each time series model for each spectral band
         ("rmse", np.float32, TOTAL_BAND_FLEX),  # RMSE for each time series model for each spectral band
         ("magnitude", np.float32, TOTAL_BAND_FLEX),
     ]
@@ -111,8 +119,8 @@
     [
         ("t_start_since1982", np.short),
         ("num_obs", np.short),
-        ("obs", np.short, (TOTAL_BAND_FLEX_NRT, DEFAULT_CONSE)),
-        ("obs_date_since1982", np.short, DEFAULT_CONSE),
+        ("obs", np.short, (TOTAL_BAND_FLEX_NRT, SCCD_CONSE_OUTPUT)),
+        ("obs_date_since1982", np.short, SCCD_CONSE_OUTPUT),
         ("covariance", np.float32, (TOTAL_BAND_FLEX_NRT, 36)),
         ("nrt_coefs", np.float32, (TOTAL_BAND_FLEX_NRT, SCCD_NUM_C)),
         ("H", np.float32, TOTAL_BAND_FLEX_NRT),
@@ -129,10 +137,10 @@
     [
         ("t_break", np.int32),
         ("coefs", np.float32, (TOTAL_BAND_FLEX_NRT, SCCD_NUM_C)),
-        ("obs", np.short, (TOTAL_BAND_FLEX_NRT, DEFAULT_CONSE)),
-        ("obs_date_since1982", np.short, DEFAULT_CONSE),
-        ("norm_cm", np.short, DEFAULT_CONSE),
-        ("cm_angle", np.short, DEFAULT_CONSE),
+        ("obs", np.short, (TOTAL_BAND_FLEX_NRT, SCCD_CONSE_OUTPUT)),
+        ("obs_date_since1982", np.short, SCCD_CONSE_OUTPUT),
+        ("norm_cm", np.short, SCCD_CONSE_OUTPUT),
+        ("cm_angle", np.short, SCCD_CONSE_OUTPUT),
     ],
     align=True,
 )