Tutorial

Understanding PyRadar’s modules

  • pyradar.core

    This module deals with SAR images and also contains equalization algorithms.

    This module contains the following functions:

    • create_dataset_from_path(image_path) from the path to a SAR image, it creates a data structure (a dataset) to manage the image’s information. This data structure is defined in an external library (Gdal).

    • get_band_from_dataset(dataset) extracts the only usable band (for our purposes) from the dataset passed as parameter. NB: we are dealing only with images which can contain only one band, as radar images are black and white.

    • get_band_min_max(band) returns a Python tuple with the maximum and minimum values for the band passed as parameter.

    • read_image_from_band(band, xoff, yoff, win_xsize, win_ysize) reads the band into numpy’s bidirectional array (or matrix), a simpler and more natural format.

      The meaning of the different parameters is as follows:

      • xoff and yoff: offset over the x and y axis where the image data should start being read.
      • win_xsize y win_ysize: window size in height and width.
    • get_geoinfo(dataset, cast_to_int) extract the georeferencing information from the dataset. “cast_to_int” implies whether the georeferencing data are represented as strings or raw numbers. For the time being, it is not employed by any of the other algorithms, but it could be useful to extend PyRadar with georeferencing functionality.

    • save_image(img_dest_dir, filename, img) saves an image in numpy array format to the folder img_dest_dir with file name filename.

      NB: img should have values in the range [0:255]. Outside that range, the values should be normalized using the equalization algorithms in the same module.

    • equalization_using_histogram(img) normalizes the values in img to the range [0:255], using the function equalize_histogram (which in turn uses histogram_eq(img)).

    • equalize_histogram(img, histogram, cfs) given both the histogram and CDF for img, normalize its values to the range [0:255] (using equalization_using_histogram).

    • naive_equalize_image(img, input_range, output_range) a simple and straightforward normalization from range input_range to the range output_range.

    This the standard procedure for opening, reading and saving a SAR image using PyRadar. In the remainder examples, we will omit these steps and we will refer to them as “basic reading steps”, from the imports until the call to the function “read_image_from_band” (inclusive). The following example shows how to use “naive_equalize_image”. We should follow the basic reading steps and then add the following piece of code:

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    # get actual range
    input_range = image.min(), image.max()
    # set new range
    output_range = 0, 255
    # equalize image
    image_eq = naive_equalize_image(image, input_range, output_range)
    # save image in current directory
    save_image(IMG_DEST_DIR, "image_sar", image_eq)
    

    Gdal is a library to read and write geospatial raster data and it distributed under MIT license by the Open Source Geospatial Foundation.

  • filters

    This module contains the speckle noise filters:

    • Frost
    • Kuan
    • Lee
    • Improved Lee

    They follow the mathematical models described in the filters section. Besides these, there are also implementations of the classic mean and median filters. This module can be easily expanded with new filters.

    Besides the algorithms, there are a series of functions that help verify the correctness of the algorithms at run time. This should simplify testing new filters.

    Module functions:

    • frost_filter(img, damping_factor, win_size) implementation of Frost filtering over the image img, taking as parameters the damping_factor and the window size win_size. Default values:

      • damping_factor=2.0
      • win_size=3.
    • kuan_filter(img, win_size, cu) apply the Kuan filter to an image img, taking as parameters the window size win_size and the noise variation rate cu. Default values: win_size=3 y cu=0.25

    • lee_filter(img, win_size, cu) apply the Lee filter to an image img, taking as parameters as image img, taking as parameters the window size win_size and the noise variation rate cu. Default values: win_size=3 y cu=0.25

    • lee_enhanced_filter(img, win_size, k, cu, cmax) applies the Improved Lee filter with the following parameters:

      • the image img,
      • the window size win_size (default: 3),
      • the dumping factor k (default: 1.0),
      • image maximum variation coefficient cmax (default: 1.73).
    • mean_filter(img, win_size) applies a traditional lo pass filter (the mean filter). It takes as parameters the image img and the window size win_size. The default value of win_size is 3.

    • median_filter(img, win_size) applies another traditional lo pass filter (the median filter). It takes as parameters the image img and the window size win_size. The default value of win_size is 3.

    • Test harness functions

    • assert_window_size(win_size) verifies the windows size is a multiple of 3 and positive, otherwise it raises a Python exception.

    • assert_indices_in_range(width, height, xleft, xright, yup, ydown) verifies the indices of the sliding window fall into expected values.

      That it, the following invariant should hold: (0 <= xleft and xright <= width and 0 <= yup and ydown <= height)

      If it does not hold, it raises a Python exception.

    Example usage for the filters:

    After executing the “basic reading steps”, the image to be used for filtering should available in the variable “image”.

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    from pyradar.filters.frost import frost_filter
    from pyradar.filters.kuan import kuan_filter
    from pyradar.filters.lee import lee_filter
    from pyradar.filters.lee_enhanced import lee_enhanced_filter
    from pyradar.filters.median import median_filter
    from pyradar.filters.mean import mean_filter
    
    # filters parameters
    # window size
    winsize = 9
    # damping factor for frost
    k_value1 = 2.0
    # damping factor for lee enhanced
    k_value2 = 1.0
    # coefficient of variation of noise
    cu_value = 0.25
    # coefficient of variation for lee enhanced of noise
    cu_lee_enhanced = 0.523
    # max coefficient of variation for lee enhanced
    cmax_value = 1.73
    
    # frost filter
    image_frost = frost_filter(image, damping_factor=k_value1, win_size=winsize)
    # kuan filter
    image_kuan = kuan_filter(image, win_size=winsize, cu=cu_value)
    # lee filter
    image_lee = lee_filter(image, win_size=winsize, cu=cu_value)
    # lee enhanced filter
    image_lee_enhanced = lee_enhanced_filter(image, win_size=winsize, k=k_value2,
                                             cu=cu_lee_enhanced, cmax=cmax_value)
    # mean filter
    image_mean = mean_filter(image, win_size=winsize)
    # median filter
    image_median = median_filter(image, win_size=winsize)
    
  • pyradar.utils.timer a small timer to profile Python execution time

    A small module to profile the “wall time” of the execution of some functions. Wall time is the time a particular function is executing, and it includes Operating System overhead. Even though is not very precise, it is useful as reference to measure the impact of different optimizations.

    Example of use:

    This utility is used within the code itself.

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    from pyradar.utils.timeutils import Timer
    
    # crea y arranca el timer
    simple_timer = Timer()
    # procedimiento que queremos medir
    result = function(arg1, arg2)
    # paramos el timer
    simple_timer.stop_timer()
    #imprimimos los resultados y los guardamos en diff
    diff = simple_timer.calculate_time_elapsed(print_value=True)
    
  • pyradar.utils.sar_debugger

    This module groups debugging tools for algorithms that manipulate SAR images. Over time, it should grow but currently it has only one function, take_snapshot().

    • takesnapshot(img) take a snapshot of the image img and saves it to disk. It can be used to capture intermediate stages of the classification algorithms.

    Example of use:

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    from pyradar.utils.sar_debugger import take_snapshot
    
    MAX_ITER = 1000
    
    for iter in xrange(0, MAX_ITER):
        image = some_algorithm(image)
        take_snapshot(image, iteration_step=iter)
    
  • pyradar.utils.system_info obtains information about the Operating System, Hardware and Software

    This module allows for obtaining detailed Operating System information in a simple way. It is used for error reporting, to diagnose Operating System-related issues.

    Example of use:

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    from pyradar.utils.system_info import get_system_info
    from pyradar.utils.system_info import print_info
    
    info = get_system_info()
    print_info(info)
    
  • pyradar.utils.statutils statistical utilities

    This module contains statistical utilities of general interest to the image processing community. In the same way as SAR Debugger, this module can be easily extended as needed.

    • compute_cfs() takes as parameter a histogram produced by numpy, it produces a table with all the accumulated frequencies.
    • calculate_pdf_for_pixel() compute the probability of a particular value appearing in the image, where the probability is given by the amount of actual times the value appears * total number of elements.
    • calculate_cdf_for_pixel() compute the value of a pixel in the cumulative distribution function.
    • ``compute_cdfs() computes the cumulative distribution frequency for each value in the image.

    Example of use

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    import numpy as np
    from pyradar.utils.statutils import compute_cfs
    from pyradar.utils.statutils import calculate_pdf_for_pixel
    from pyradar.utils.statutils import calculate_cdf_for_pixel
    from pyradar.utils.statutils import compute_cdfs
    arr = np.array([31, 49, 19, 62, 24, 45, 23, 51, 55, 60, 40, 35,
                    54, 26, 57, 37, 43, 65, 18, 41, 50, 56, 4, 54,
                    39, 52, 35, 51, 63, 42])
    max_value = arr.max()
    min_value = arr.min()
    start, stop, step = int(min_value), int(max_value + 2), 1
    
    histogram, bin_edge = np.histogram(arr, xrange(start, stop, step))
    compute_cfs(histogram)
    
    # >>> array([ 1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,  1,
    #             1,  2,  3,  3, 3,  3,  4,  5,  5,  6,  6,  6,  6,
    #             6,  7,  7,  7,  7,  9,  9, 10, 10, 11, 12, 13, 14,
    #            15, 15, 16, 16, 16, 16, 17, 18, 20, 21, 21, 23, 24,
    #            25, 26, 26, 26, 27, 27, 28, 29, 29, 30])
    
    
    calculate_pdf_for_pixel(arr, histogram, bin_edge, 54)
    # >>> 0.066666666666666666
    
    calculate_pdf_for_pixel(arr, histogram, bin_edge, 20)
    # >>> 0.0
    
    calculate_pdf_for_pixel(arr, histogram, bin_edge, 18)
    # >>> 0.033333333333333333
    
    calculate_cdf_for_pixel(arr, histogram, bin_edge, 4)
    # >>> 0.033333333333333333
    
    calculate_cdf_for_pixel(arr, histogram, bin_edge, 50)
    # >>> 0.59999999999999998
    
    compute_cdfs(arr, histogram, bin_edge)
    
    # >>> array([ 0.03333333,  0.03333333,  0.03333333,  0.03333333,  0.03333333,
    #             0.03333333,  0.03333333,  0.03333333,  0.03333333,  0.03333333,
    #             0.03333333,  0.03333333,  0.03333333,  0.03333333,  0.06666667,
    #             0.1       ,  0.1       ,  0.1       ,  0.1       ,  0.13333333,
    #             0.16666667,  0.16666667,  0.2       ,  0.2       ,  0.2       ,
    #             0.2       ,  0.2       ,  0.23333333,  0.23333333,  0.23333333,
    #             0.23333333,  0.3       ,  0.3       ,  0.33333333,  0.33333333,
    #             0.36666667,  0.4       ,  0.43333333,  0.46666667,  0.5       ,
    #             0.5       ,  0.53333333,  0.53333333,  0.53333333,  0.53333333,
    #             0.56666667,  0.6       ,  0.66666667,  0.7       ,  0.7       ,
    #             0.76666667,  0.8       ,  0.83333333,  0.86666667,  0.86666667,
    #             0.86666667,  0.9       ,  0.9       ,  0.93333333,  0.96666667,
    #             0.96666667,  1.        ])
    
  • pyradar.classifiers.kmeans

    Example of use

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    # this should be placed at the top with all the imports
    from pyradar.classifiers.kmeans import kmeans_classification
    
    # number of clusters
    k= 4
    # max number of iterations
    iter_max = 1000
    # run K-Means
    class_image = kmeans_classification(image, k, iter_max)
    
    # equalize class image to 0:255
    class_image_eq = equalization_using_histogram(class_image)
    # save it
    save_image(IMG_DEST_DIR, "class_image_eq", class_image_eq)
    # also save original image
    image_eq = equalization_using_histogram(image)
    # save it
    save_image(IMG_DEST_DIR, "image_eq", image_eq)
    
  • pyradar.classifiers.isodata

    Example of use

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    # this should be placed at the top with all the imports
    from pyradar.classifiers.isodata import isodata_classification
    
    params = {"K": 15, "I" : 100, "P" : 2, "THETA_M" : 10, "THETA_S" : 0.1,
              "THETA_C" : 2, "THETA_O" : 0.01}
    
    # run Isodata
    class_image = isodata_classification(img, parameters=params)
    
    # equalize class image to 0:255
    class_image_eq = equalization_using_histogram(class_image)
    # save it
    save_image(IMG_DEST_DIR, "class_image_eq", class_image_eq)
    # also save original image
    image_eq = equalization_using_histogram(image)
    # save it
    save_image(IMG_DEST_DIR, "image_eq", image_eq)
    
  • pyradar.simulate.image_simulator

    Example of use

    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    
    from pyradar.simulate.image_simulator import ImageSimulator
    from pyradar.utils.timeutils import Timer
    pylab.close()
    
    timer = Timer()
    width, height = 2000, 2000
    
    gamma_ims = ImageSimulator(width, height)
    k_ims = ImageSimulator(width, height)
    noise_layer_ims = ImageSimulator(width, height)
    
    gamma_params = {'scale': 2.0, 'shape': 3.0}
    k_params = {'mean': 2.0, 'shape': 2.0}
    noise_layer_params = {'df': 3}
    
    gamma_ims.generate_image_layer(distribution='gamma', params=gamma_params)
    k_ims.generate_image_layer(distribution='k', params=k_params)
    noise_layer_ims.generate_noise_layer(distribution='chisquare', params=noise_layer_params)
    
    # Make some noise!
    gamma_ims.noise_layer = noise_layer_ims.noise_layer
    k_ims.noise_layer = noise_layer_ims.noise_layer
    gamma_ims.generate_noisy_layer()
    k_ims.generate_noisy_layer()
    
    timer.calculate_time_elapsed(print_value=True)
    # Export the files:
    gamma_ims.export_image_layer(layer_name='image_layer', filename='gamma_img_layer',
                                 path_to='.')
    k_ims.export_image_layer(layer_name='image_layer', filename='k_img_layer',
                             path_to='.')
    gamma_ims.export_image_layer(layer_name='noisy_image', filename='gamma_noisy_img',
                                 path_to='.')
    k_ims.export_image_layer(layer_name='noisy_image', filename='k_noisy_img',
                             path_to='.')
    timer.calculate_time_elapsed(print_value=True)
    
    # Make a plot:
    print 'Making a plot to "plot_img.png":'
    pylab.close()
    gamma_ims.plot_layer_histogram(layer_name='image_layer', filename='plot_gamma_img')
    k_ims.plot_layer_histogram(layer_name='image_layer', filename='plot_k_img')
    
    timer.stop_timer()
    timer.calculate_time_elapsed(print_value=True)
    
Read the Docs v: latest
Versions
latest
Downloads
PDF
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.