User Guide¶
General Usage Advice¶
You should use the classes for calculating the metrics. The functions are only intended for advanced users who want to use the metrics in a non-standard way. A batch mode is provided for batch processing of images.
Workflow¶
Images are first loaded from .raw files or .mhd files and their corresponding .raw file, normalized to the chosen data
range (if the parameter normalize=True
is set) and then compared. The scores are then calculated and can be printed.
If using paths file names need to be given with the bit depth denoted as a suffix (e.g. _8bit.raw
, _16bit.raw
) and
the dimensions of the images need to be given in the file name (e.g. 512x512x512
). The images are assumed to be
grayscale. Treatment of color images is planned for later versions.
The metrics are implemented to calculate the scores for an 8-bit data range (0-255) per default. For some metrics the
resulting score is different for different data ranges. When calculating several metrics for the same image, the same
data range should be used for all metrics. The data range can be changed by setting the parameter data_range
for each
metric. This parameter primarily affects the loading behaviour of the class instances when not using the
load_data()
function directly as described further below, but for some metrics setting the data range is
necessary to calculate the score (e.g. PSNR).
Examples¶
Better:
import viqa
from viqa import load_data
from viqa.utils import normalize_data
## load images
file_path_img_r = 'path/to/reference_image_8bit_512x512x512.raw'
file_path_img_m = 'path/to/modified_image_8bit_512x512x512.raw'
img_r = load_data(
file_path_img_r,
data_range=1,
normalize=False,
) # data_range ignored due to normalize=False
img_m = load_data(file_path_img_m) # per default: batch=False, normalize=False
# --> both images are loaded as 8-bit images
# calculate and print RMSE score
rmse = viqa.RMSE()
score_rmse = rmse.score(img_r, img_m) # RMSE does not need any parameters
rmse.print_score(decimals=2)
# normalize to 16-bit
img_r = normalize_data(img_r, data_range_output=(0, 65535))
img_m = load_data(img_m, data_range=65535, normalize=True)
# --> both functions have the same effect
# calculate and print PSNR score
psnr = viqa.PSNR(data_range=65535) # PSNR needs data_range to calculate the score
score_psnr = psnr.score(img_r, img_m)
psnr.print_score(decimals=2)
# set optional parameters for MAD as dict
calc_parameters = {
'block_size': 16,
'block_overlap': 0.75,
'beta_1': 0.467,
'beta_2': 0.130,
'luminance_function': {'b': 0, 'k': 0.02874, 'gamma': 2.2},
'orientations_num': 4,
'scales_num': 5,
'weights': [0.5, 0.75, 1, 5, 6]
}
# calculate and print MAD score
mad = viqa.MAD(data_range=65535) # MAD needs data_range to calculate the score
score_mad = mad.score(img_r, img_m, dim=2, **calc_parameters)
mad.print_score(decimals=2)
Possible, but worse (recommended only if you want to calculate a single metric):
import viqa
file_path_img_r = 'path/to/reference_image_512x512x512_16bit.raw'
file_path_img_m = 'path/to/modified_image_512x512x512_16bit.raw'
load_parameters = {'data_range': 1, 'normalize': True}
# data_range is set to 1 to normalize the images
# to 0-1 and for calculation, if not set 255 would
# be used as default for loading and calculating
# the score
psnr = viqa.PSNR(**load_parameters) # load_parameters necessary due to direct loading by class
# also PSNR needs data_range to calculate the score
# if images would not be normalized, data_range should be
# 65535 for 16-bit images for correct calculation
score = psnr.score(file_path_img_r, file_path_img_m)
# --> images are loaded as 16-bit images and normalized to 0-1 via the `load_data` function
# called by the score method
psnr.print_score(decimals=2)
Tip
It is recommended to load the images directly with the load_data()
function first and then pass the image
arrays to the metrics functions. You can also pass the image paths directly to the metrics functions. In this case,
the images will be loaded with the given parameters. This workflow is only recommended if you want to calculate a
single metric.
Important
The current recommended usage files are the Jupyter Notebooks on the Github page. Additional information can be found in the documentation of the individual metrics under API Reference.