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)