ImageFusion (version 0.0.1)

starfm_job: Execute a single self-contained self-contained time-series imagefusion job using STARFM

Description

A wrapper function for execute_starfm_job_cpp. Intended to execute a single job, that is a number of predictions based on the same input pair(s). It ensures that all of the arguments passed are of the correct type and creates sensible defaults.

Usage

starfm_job(
  input_filenames,
  input_resolutions,
  input_dates,
  pred_dates,
  pred_filenames,
  pred_area,
  winsize,
  date1,
  date3,
  n_cores,
  logscale_factor,
  spectral_uncertainty,
  temporal_uncertainty,
  number_classes,
  hightag,
  lowtag,
  MASKIMG_options,
  MASKRANGE_options,
  output_masks,
  use_nodata_value,
  use_strict_filtering,
  double_pair_mode,
  use_temp_diff_for_weights,
  do_copy_on_zero_diff,
  verbose = TRUE
)

Arguments

input_filenames

A string vector containing the filenames of the input images

input_resolutions

A string vector containing the resolution-tags (corresponding to the arguments hightag and lowtag, which are by default "high" and "low") of the input images.

input_dates

An integer vector containing the dates of the input images.

pred_dates

An integer vector containing the dates for which images should be predicted.

pred_filenames

A string vector containing the filenames for the predicted images. Must match pred_dates in length and order. Must include an extension relating to one of the drivers supported by GDAL, such as ".tif".

pred_area

(Optional) An integer vector containing parameters in image coordinates for a bounding box which specifies the prediction area. The prediction will only be done in this area. (x_min, y_min, width, height). By default will use the entire area of the first input image.

winsize

(Optional) Window size of the rectangle around the current pixel. Default is 51.

date1

(Optional) Set the date of the first input image pair. By default, will use the pair with the lowest date value.

date3

(Optional) Set the date of the second input image pair. By default, will use the pair with the highest date value. Disregarded if using double pair mode.

n_cores

(Optional) Set the number of cores to use when using parallelization. Default is 1.

logscale_factor

(Optional) When using a positive scale, the logistic weighting formula is used, which reduces the influence of spectral and temporal differences. Default is 0, i. e. logistic formula not used

spectral_uncertainty

(Optional) This spectral uncertainty value will influence the spectral difference value. Default is 1 for 8 bit images (INT1U and INT1S), 50 otherwise.

temporal_uncertainty

(Optional) This spectral uncertainty value will influence the spectral difference value. Default is 1 for 8 bit images (INT1U and INT1S), 50 otherwise.

number_classes

(Optional) The number of classes used for similarity. Note all channels of a pixel are considered for similarity. So this value holds for each channel, e. g. with 3 channels there are n^3 classes. Default: 40.

hightag

(Optional) A string which is used in input_resolutions to describe the high-resolution images. Default is "high".

lowtag

(Optional) A string which is used in input_resolutions to describe the low-resolution images. Default is "low".

MASKIMG_options

(Optional) A string containing information for a mask image (8-bit, boolean, i. e. consists of 0 and 255). "For all input images the pixel values at the locations where the mask is 0 is replaced by the mean value." Example: --mask-img=some_image.png

MASKRANGE_options

(Optional) Specify one or more intervals for valid values. Locations with invalid values will be masked out. Ranges should be given in the format '[<float>,<float>]', '(<float>,<float>)', '[<float>,<float>' or '<float>,<float>]'. There are a couple of options:'

• "--mask-valid-ranges" Intervals which are marked as valid. Valid ranges can excluded from invalid ranges or vice versa, depending on the order of options.

• "--mask-invalid-ranges" Intervals which are marked as invalid. Invalid intervals can be excluded from valid ranges or vice versa, depending on the order of options.

• "--mask-high-res-valid-ranges" This is the same as --mask-valid-ranges, but is applied only for the high resolution images.

• "--mask-high-res-invalid-ranges" This is the same as --mask-invalid-ranges, but is applied only for the high resolution images.

• "--mask-low-res-valid-ranges" This is the same as --mask-valid-ranges, but is applied only for the low resolution images.

• "--mask-low-res-invalid-ranges" This is the same as --mask-invalid-ranges, but is applied only for the low resolution images.

output_masks

(Optional) Write mask images to disk? Default is "false".

use_nodata_value

(Optional) Use the nodata value as invalid range for masking? Default is "true".

use_strict_filtering

(Optional) Use strict filtering, which means that candidate pixels will be accepted only if they have less temporal and spectral difference than the central pixel (like in the paper). Default is "false".

double_pair_mode

(Optional) Use two dates date1 and date3 for prediction, instead of just date1 for all predictions? Default is "true" if all the pred dates are in between input pairs, and "false" otherwise. Note: It may be desirable to predict in double-pair mode where possible, as in the following example: [(7) 10 12 (13) 14] , where we may wish to predict 10 and 12 in double pair mode, but can only predict 14 in single-pair mode. Do achieve this it is necessary to split the task into different jobs. Default is "true" if all pred_dates are between pair dates and "false" otherwise.

use_temp_diff_for_weights

(Optional) Use temporal difference in the candidates weight (like in the paper)? Default is to use temporal weighting in double pair mode, and to not use it in single pair mode.

do_copy_on_zero_diff

(Optional) Predict for all pixels, even for pixels with zero temporal or spectral difference (behavior of the reference implementation). Default is "false".

verbose

(Optional) Print progress updates to console? Default is "true".

Value

Nothing. Output files are written to disk. The Geoinformation for the output images is adopted from the first input pair images.

Details

Executes the STARFM algorithm to create a number of synthetic high-resolution images from either two pairs (double pair mode) or one pair (single pair mode) of matching high- and low-resolution images. Assumes that the input images already have matching size. See the original paper for details.

• For the weighting (10) states: \(C = S T D\) but we use \(C = (S+1)(T+1)D\), according to the reference implementation. With logscale_factor, the weighting formula can be changed to \(C = ln{(Sb+2)}ln{(Tb+1)D}\)

• In addition to the temporal uncertainty \(\sigma_t\) (see temporal_uncertainty) and the spectral uncertainty\( \sigma_s\) (see spectral_uncertainty) there will be used a combined uncertainty \(\sigma_c := \sqrt{\sigma_t^2 + \sigma_s^2} \). This will be used in the candidate weighting: If \((S + 1) \, (T + 1) < \sigma_c \), then \(C = 1 \) instead of the formula above.

• Considering candidate weighting again, there is an option use_tempdiff_for_weights to not use the temporal difference for the weighting (also not for the combined uncertainty check above), i. e. T = 0 then. This is also the default behavior.

• The basic assumption of the original paper that with zero spectral or temporal difference the central pixel will be chosen is wrong since there might be multiple pixels with zero difference within one window. Also due to the addition of 1 to the spectral and temporal differences, the weight will not increase so dramatically from a zero difference. However, these assumptions can be enforced with do_copy_on_zero_diff, which is the default behavior.

• The paper states that a good candidate should satisfy (15) and (16). This can be set with use_strict_filtering, which is by default used. However the other behavior, that a candidate should fulfill (15) or (16), as in the reference implementation, can be also be selected with that option.

• The paper uses max in (15) and (16), which would choose the largest spectral and temporal difference from all input pairs (only one or two are possible). Since this should filter out bad candidates, we believe this is a mistake and should be min instead of max, like it is done in the reference implementation. So this implementation uses min here.

References

Gao, Feng, et al. "On the blending of the Landsat and MODIS surface reflectance: Predicting daily Landsat surface reflectance." IEEE Transactions on Geoscience and Remote sensing 44.8 (2006): 2207-2218.

Examples

# NOT RUN {
# Load required libraries
library(ImageFusion)
library(raster)
# Get filesnames of high resolution images
landsat <- list.files(
  system.file("landsat/filled",
              package = "ImageFusion"),
  ".tif",
  recursive = TRUE,
  full.names = TRUE
)

# Get filesnames of low resolution images
modis <- list.files(
  system.file("modis",
              package = "ImageFusion"),
  ".tif",
  recursive = TRUE,
  full.names = TRUE
)

#Select the first two landsat images 
landsat_sel <- landsat[1:2]
#Select the corresponding modis images
modis_sel <- modis[1:10]
# Create output directory in temporary folder
out_dir <- file.path(tempdir(),"Outputs")
if(!dir.exists(out_dir)) dir.create(out_dir, recursive = TRUE)
#Run the job, fusing two images
starfm_job(input_filenames = c(landsat_sel,modis_sel),
           input_resolutions = c("high","high",
                                 "low","low","low",
                                 "low","low","low",
                                 "low","low","low","low"),
           input_dates = c(68,77,68,69,70,71,72,73,74,75,76,77),
           pred_dates = c(73,77),
           pred_filenames = c(file.path(out_dir,"starfm_73.tif"),
                              file.path(out_dir,"starfm_77.tif"))
)
# remove the output directory
unlink(out_dir,recursive = TRUE)
# }