Modules & Classes¶

The `aggregate` Module¶

Aggregate a list of numbers using the specified method.

Aggregators:

NAME DESCRIPTION

l_1 return the average

l_2 average the squares and return the square root

l_4 average the quads and return the fourth root

l_inf return the maximum

aggregate.main()[source]¶: Run exquires-aggregate.

The `Aggregate` Class¶

class aggregate.Aggregate(values)[source]¶

Bases: object

This class provide various ways of aggregating error data.

Parameters:	values (list of numbers) – numbers to aggregate

l_1()[source]¶

Return the average.

Returns:	the average
Return type:	float

l_2()[source]¶

Average the squares and return the square root.

Returns:	the square root of the average of the squares
Return type:	float

l_4()[source]¶

Average the quads and return the fourth root.

Returns:	the fourth root of the average of the quads
Return type:	float

l_inf()[source]¶

Return the maximum.

Returns:	the maximum
Return type:	float

The `compare` Module¶

Print the result of calling a difference metric on two image files.

Difference Metrics:

NAME DESCRIPTION

srgb_1 $\ell_1$ norm in sRGB colour space

srgb_2 $\ell_2$ norm in sRGB colour space

srgb_4 $\ell_4$ norm in sRGB colour space

srgb_inf $\ell_\infty$ norm in sRGB colour space

cmc_1 $\ell_1$ norm using the CMC(1:1) colour difference

cmc_2 $\ell_2$ norm using the CMC(1:1) colour difference

cmc_4 $\ell_4$ norm using the CMC(1:1) colour difference

cmc_inf $\ell_\infty$ norm using the CMC(1:1) colour difference

xyz_1 $\ell_1$ norm in XYZ colour space

xyz_2 $\ell_2$ norm in XYZ colour space

xyz_4 $\ell_4$ norm in XYZ colour space

xyz_inf $\ell_\infty$ norm in XYZ colour space

blur_1 MSSIM-inspired $\ell_1$ norm

blur_2 MSSIM-inspired $\ell_2$ norm

blur_4 MSSIM-inspired $\ell_4$ norm

blur_inf MSSIM-inspired $\ell_\infty$ norm

mssim Mean Structural Similarity Index (MSSIM)

compare._get_blurlist()[source]¶: Private method to return a Gaussian blur mask.

Note

This is a private function called by blur_1(), blur_2(), blur_4(), blur_inf(), and mssim().

compare.main()[source]¶: Run exquires-compare.

The `Metrics` Class¶

class compare.Metrics(image1, image2, maxval=65535)[source]¶

Bases: object

This class contains error metrics to be used on sRGB images.

The $\ell_1$ , $\ell_2$ , $\ell_4$ , and $\ell_\infty$ metrics are normalized by L, the largest possible pixel value of the input images (the lowest is assumed to be 0). The range of output for these metrics is [0, 100].

The MSSIM metric produces output in the range [-1, 1], but it is unlikely that a negative value will be produced, as the image features must differ greatly. For instance, a pure white image compared with a pure black image produces a result slightly greater than 0.

The CMC and XYZ errors can be slightly outside the range [0, 100], but this will not occur for most image pairs.

Note

By default, a Metrics object is configured to operate on 16-bit images.

Parameters:	image1 (path) – first image to compare (reference image) image2 (path) – second image to compare (test image) L (integer) – highest possible pixel value (default=65535)

blur_1()[source]¶

Compute MSSIM-inspired $\ell_1$ error.

This method performs the same greyscale conversion, Gaussian blur, and cropping as MSSIM, but returns the $\ell_1$ error of the cropped image.

See (2) for details on how the blurred images are compared.

Note

The images are converted to grayscale before applying Gaussian blur. The grayscale conversion is equivalent to taking the Y channel in YIQ colour space.

Returns:	MSSIM-inspired $\ell_1$ error
Return type:	float

blur_2()[source]¶

Compute MSSIM-inspired $\ell_2$ error.

This method performs the same greyscale conversion, Gaussian blur, and cropping as MSSIM, but returns the $\ell_2$ error of the cropped image.

See (3) for details on how the blurred images are compared.

Note

The images are converted to grayscale before applying Gaussian blur. The grayscale conversion is equivalent to taking the Y channel in YIQ colour space.

Returns:	MSSIM-inspired $\ell_2$ error
Return type:	float

blur_4()[source]¶

Compute MSSIM-inspired $\ell_4$ error.

This method performs the same greyscale conversion, Gaussian blur, and cropping as MSSIM, but returns the $\ell_4$ error of the cropped image.

See (4) for details on how the blurred images are compared.

Note

The images are converted to grayscale before applying Gaussian blur. The grayscale conversion is equivalent to taking the Y channel in YIQ colour space.

Returns:	MSSIM-inspired $\ell_4$ error
Return type:	float

blur_inf()[source]¶

Compute MSSIM-inspired $\ell_\infty$ error.

This method performs the same greyscale conversion, Gaussian blur, and cropping as MSSIM, but returns the $\ell_\infty$ error of the cropped image.

See (5) for details on how the blurred images are compared.

Note

The images are converted to grayscale before applying Gaussian blur. The grayscale conversion is equivalent to taking the Y channel in YIQ colour space.

Returns:	MSSIM-inspired $\ell_\infty$ error
Return type:	float

cmc_1()[source]¶

Compute $\ell_1$ error in Uniform Colour Space (UCS).

This method imports the images into Lab colour space, then calculates delta-E CMC(1:1) and returns the average.

See (2) for details on how the standard $\ell_1$ norm is computed.

Returns:	$\ell_1$ error in Uniform Colour Space (UCS)
Return type:	float

cmc_2()[source]¶

Compute $\ell_2$ error in Uniform Colour Space (UCS).

This method imports the images into Lab colour space, then calculates delta-E CMC(1:1) and returns the $\ell_2$ norm.

See (3) for details on how the standard $\ell_2$ norm is computed.

Returns:	$\ell_2$ error in Uniform Colour Space (UCS)
Return type:	float

cmc_4()[source]¶

Compute $\ell_4$ error in Uniform Colour Space (UCS).

This method imports the images into Lab colour space, then calculates delta-E CMC(1:1) and returns the $\ell_4$ norm.

See (4) for details on how the standard $\ell_4$ norm is computed.

Returns:	$\ell_4$ error in Uniform Colour Space (UCS)
Return type:	float

cmc_inf()[source]¶

Compute $\ell_\infty$ error in Uniform Colour Space (UCS).

This method imports the images into Lab colour space, then calculates delta-E CMC(1:1) and returns the $\ell_\infty$ norm.

See (5) for details on how the standard $\ell_\infty$ norm is computed.

Returns:	$\ell_\infty$ error in Uniform Colour Space (UCS)
Return type:	float

mssim()[source]¶

Compute the Mean Structural Similarity Index (MSSIM).

The equation for SSIM is

(1) $SSIM(x,y) = \frac{(2\mu_x\mu_y + C_1)(2\sigma_{xy} + C_2)} {(\mu_x^2 + \mu_y^2 + C_1)(\sigma_x^2 + \sigma_y^2 + C_2)}$

where $\mu_x$ and $\mu_y$ are the sample means, $\sigma_x$ and $\sigma_y$ are the standard deviations, and $\sigma_{xy}$ is the correlation coefficient between images $x$ and $y$ .

Once the SSIM map is computed, the border is trimmed by 5 pixels and the mean is returned.

This version is slightly more efficient than the method proposed by Wang et. al. because it reduces the number of Gaussian blurs from 5 to 4.

Note

The images are converted to grayscale before applying Gaussian blur. The grayscale conversion is equivalent to taking the Y channel in YIQ colour space.

Returns:	mean SSIM
Return type:	float

srgb_1()[source]¶

Compute $\ell_1$ error in sRGB colour space.

The equation for the $\ell_1$ error, aka Average Absolute Error (AAE), is

(2) $\ell_1(x,y) = \frac{1}{N} \sum_{i=1}^{N} |x_i - y_i|$

where $x$ and $y$ are the images to compare, each consisting of $N$ pixels.

Returns:	$\ell_1$ error
Return type:	float

srgb_2()[source]¶

Compute $\ell_2$ error in sRGB colour space.

The equation for the $\ell_2$ error, aka Root Mean Squared Error (RMSE), is

(3) $\ell_2(x,y) = \sqrt{\frac{1}{N} \sum_{i=1}^{N} (x_i - y_i)^2}$

where $x$ and $y$ are the images to compare, each consisting of $N$ pixels.

Returns:	$\ell_2$ error
Return type:	float

srgb_4()[source]¶

Compute $\ell_4$ error in sRGB colour space.

The equation for the $\ell_4$ error is

(4) $\ell_4(x,y) = \sqrt[4]{\frac{1}{N} \sum_{i=1}^{N} (x_i - y_i)^4}$

where $x$ and $y$ are the images to compare, each consisting of $N$ pixels.

Returns:	$\ell_4$ error
Return type:	float

srgb_inf()[source]¶

Compute $\ell_\infty$ error in sRGB colour space.

The equation for the $\ell_\infty$ error, aka Maximum Absolute Error (MAE), is

(5) $\ell_\infty(x,y) = \max_{1 \le i \le N} |x_i - y_i|$

where $x$ and $y$ are the images to compare, each consisting of $N$ pixels.

Returns:	$\ell_\infty$ error
Return type:	float

xyz_1()[source]¶

Compute $\ell_1$ error in XYZ Colour Space.

This method imports the images into XYZ colour space, then calculates the $\ell_1$ error.

See (2) for details on how the standard $\ell_1$ norm is computed.

Returns:	$\ell_1$ error in XYZ Colour Space
Return type:	float

xyz_2()[source]¶

Compute $\ell_2$ error in XYZ Colour Space.

This method imports the images into XYZ colour space, then calculates the $\ell_2$ error.

See (3) for details on how the standard $\ell_2$ norm is computed.

Returns:	$\ell_2$ error in XYZ Colour Space
Return type:	float

xyz_4()[source]¶

Compute $\ell_4$ error in XYZ Colour Space.

This method imports the images into XYZ colour space, then calculates the $\ell_4$ error.

See (4) for details on how the standard $\ell_4$ norm is computed.

Returns:	$\ell_4$ error in XYZ Colour Space
Return type:	float

xyz_inf()[source]¶

Compute $\ell_\infty$ error in XYZ Colour Space.

This method imports the images into XYZ colour space, then calculates the $\ell_\infty$ error.

See (5) for details on how the standard $\ell_\infty$ norm is computed.

Returns:	$\ell_\infty$ error in XYZ Colour Space
Return type:	float

The `correlate` Module¶

Produce a Spearman’s rank cross-correlation matrix for the specified group.

By default, the -M/--metric option is selected. You can select one of the following cross-correlation groups:

-I/--image

-D/--down

-R/--ratio

-M/--metric

You can also select which upsamplers to consider when computing the matrix by using the -U/--up option.

correlate._get_group_and_ranks(args)[source]¶

Return the correlation group and ranks.

Note

This is a private function called by _print_matrix().

Parameters:	args (`argparse.Namespace`) – arguments args.dbase_file (path) – database file args.image (list of strings) – selected image names args.down (list of strings) – selected downsampler names args.ratio (list of strings) – selected ratios args.up (list of strings) – selected upsampler names args.metric (list of strings) – selected metric names args.metrics_d (dict) – all metric names args.file (path) – output file args.digits (integer) – number of digits to print args.latex (boolean) – True if printing a LaTeX-formatted table args.key (string) – key for the correlation group
Returns:	the group and ranks
Return type:	string, list of lists

correlate._print_matrix(args)[source]¶

Print a cross-correlation matrix from aggregate image comparison data.

Note

This is a private function called by main().

Parameters:

args (argparse.Namespace) – arguments
args.dbase_file (path) – database file
args.image (list of strings) – selected image names
args.down (list of strings) – selected downsampler names
args.ratio (list of strings) – selected ratios
args.up (list of strings) – selected upsampler names
args.metric (list of strings) – selected metric names
args.metrics_d (dict) – all metric names
args.file (path) – output file
args.digits (integer) – number of digits to print
args.latex (boolean) – True if printing a LaTeX-formatted table
args.key (string) – key for the correlation group
args.anchor (string) – row/column to order the matrix by

correlate.main()[source]¶

Run exquires-correlate.

Parse the command-line arguments and print the cross-correlation matrix.

The `database` Module¶

Provides an interface to the sqlite3 image error database.

The `Database` Class¶

class database.Database(dbasefile)[source]¶

This class provides an interface to the sqlite3 image error database.

The database stores error data computed by exquires-run and exquires-update. This data is retrieved and used to compute the output given by exquires-report and exquires-correlate.

Parameters:	dbasefile (path) – database file to connect to

_Database__create_table(name, metrics)¶

Private method used to create a new database table.

Note

This is a private method called by add_table() and backup_table().

Parameters:	name (string) – name of the table to create metrics (list of strings) – error metrics to compute (the table columns)

add_table(image, downsampler, ratio, metrics)[source]¶

Add a new table to the database.

Each table is defined in the following way:

image, downsampler, and ratio define the table name
metrics define the columns of the table

To keep track of each table in terms of the image, downsampler, and ratio that defines it, an entry is created in the TABLEDATA table.

Parameters:	image (string) – name of the image downsampler (string) – name of the downsampler ratio (string) – resampling ratio metrics (list of strings) – names of the metrics
Returns:	the table name
Return type:	string

backup_table(name, metrics)[source]¶

Backup an existing image error table.

Parameters:	name (string) – name of the table to backup metrics (list of strings) – error metrics (columns) to backup
Returns:	name of the backup table
Return type:	string

close()[source]¶: Close the connection to the database.

delete(table, upsampler)[source]¶

Delete a row from the table.

Parameters:	table (string) – name of the table to delete from upsampler (string) – upsampler (row) to remove from the table

drop_backup(name)[source]¶

Drop a backup table once it is no longer needed.

Parameters:	name (string) – name of the backup table to drop

drop_tables(images, downsamplers, ratios)[source]¶

Drop database tables.

All tables defined by any of the images, downsamplers, or ratios are dropped. The TABLEDATA table is updated to reflect these changes.

Parameters:	images (list of strings) – names of the images downsamplers (list of strings) – names of the downsamplers ratios (list of strings) – resampling ratios

get_error_data(table, upsampler, metrics_str)[source]¶

Return a filtered row of error data.

For the upsampler row in the table, return a dictionary containing only the error data for the specified metrics.

Parameters:	table (string) – name of the table to query upsampler (string) – name of the upsampler (row) to acquire data from metrics_str (string) – metrics to return error data for (comma-separated)
Returns:	the filtered row of error data
Return type:	dict

get_tables(args)[source]¶

Return table names for these images, downsamplers, and ratios.

Parameters:	args (`argparse.Namespace`) – arguments args.image (list of strings) – names of images args.down (list of strings) – names of downsamplers args.ratio (list of strings) – resampling ratios
Returns:	names of the tables
Return type:	list of strings

insert(table, row)[source]¶

Insert a single row into the table, or update if it exists.

Parameters:	table (string) – name of the table row (dict) – row data to insert

sql_do(sql, params=())[source]¶

Perform an operation on the database and commit the changes.

Parameters:	sql (string) – SQL statement to execute and commit params (list of values) – values to fill wildcards in the SQL statement

sql_fetchall(sql, params=())[source]¶

Fetch all rows for the specified SQL query.

Parameters:	sql (string) – SQL query to execute params (list of values) – values to fill wildcards in the SQL statement
Returns:	rows specified by the SQL query
Return type:	list of dicts

The `new` Module¶

Generate a new project file to use with exquires-run.

The project file is used to specify the following components of the suite:

Images ( sRGB TIFF | 16 bits/sample (48/pixel) | 840x840 pixels )

Downsamplers

Resampling Ratios

Upsamplers

Difference Metrics

For the specified project name and list of images, a default project file will be created with the name PROJECT.ini, where PROJECT is a name specified using the -p:option:–proj option. If a name is not specified, the default name is project1.

Use the -I:option:–image option to provide a list of images to include in the project file. If no images are specified, a default image (wave.tif) is included in the project file.

Manually edit this file to customize your project.

new._add_default_downsamplers(ini)[source]¶

Add the default downsamplers to the specified .ini file.

Note

This is a private function called by main().

Parameters:	ini (`configobj.ConfigObj`) – the `.ini` file to modify

new._add_default_images(ini, image)[source]¶

Add the default images to the specified .ini file.

Note

This is a private function called by main().

Parameters:	ini (`configobj.ConfigObj`) – the `.ini` file to modify

new._add_default_metrics(ini)[source]¶

Add the default metrics to the specified .ini file.

Note

This is a private function called by main().

Parameters:	ini (`configobj.ConfigObj`) – the `.ini` file to modify

new._add_default_ratios(ini)[source]¶

Add the default ratios to the specified .ini file.

Note

This is a private function called by main().

Parameters:	ini (`configobj.ConfigObj`) – the `.ini` file to modify

new._add_default_upsamplers(ini)[source]¶

Add the default upsamplers to the specified .ini file.

Note

This is a private function called by main().

Parameters:	ini (`configobj.ConfigObj`) – the `.ini` file to modify

new._magick(method, **kwargs)[source]¶

Return an ImageMagick resize command as a string.

Blur and Kaiser beta values are passed as strings to avoid truncation.

Note

This is a private function called by _add_default_downsamplers(), _std_int_lin_tensor_mtds_1(), _std_int_lin_tensor_mtds_2(), _novel_int_lin_flt_mtds(), _std_nonint_lin_tensor_mtds(), _std_int_ewa_lin_flt_mtds(), _std_nonint_ewa_lin_flt_mtds(), and _novel_nonint_ewa_lin_flt_mtds().

Parameters:	method (string) – method to use with -resize or -distort Resize lin (boolean) – True if using a linear method dist (boolean) – True if using a -distort Resize method lobes (integer) – number of lobes blur (string) – blur value beta (string) – beta value for Kaiser method
Returns:	the ImageMagick command
Return type:	string

new._metric(method, aggregator, sort)[source]¶

Return 3-element list defining a metric, an aggregator and a sort order.

Note

This is a private function called by _add_default_metrics().

Parameters:	method (string) – image comparison metric (see exquires-compare) aggregator (string) – data aggregator (see exquires-aggregate) sort (integer) – best-to-worst order (0: ascending, 1: descending)
Returns:	metric, aggregator, and sort order
Return type:	list

new._novel_int_lin_flt_mtds(ini_ups)[source]¶

Add the novel interpolatory linear filtering methods.

Note

This is a private function called by _add_default_upsamplers().

Parameters:	ini_ups (dict) – upsamplers for the specified `.ini` file

new._novel_nonint_ewa_lin_flt_mtds(ini_ups)[source]¶

Add the novel non-interpolatory EWA linear filtering methods.

Note

This is a private function called by _add_default_upsamplers().

Parameters:	ini_ups (dict) – upsamplers for the specified `.ini` file

new._std_int_ewa_lin_flt_mtds(ini_ups)[source]¶

Add the standard interpolatory EWA linear filtering methods.

Note

This is a private function called by _add_default_upsamplers().

Parameters:	ini_ups (dict) – upsamplers for the specified `.ini` file

new._std_int_lin_tensor_mtds_1(ini_ups)[source]¶

Add the 1st part of the standard interpolatory linear tensor methods.

Note

This is a private function called by _add_default_upsamplers().

Parameters:	ini_ups (dict) – upsamplers for the specified `.ini` file

new._std_int_lin_tensor_mtds_2(ini_ups)[source]¶

Add the 2nd part of the standard interpolatory linear tensor methods.

Note

This is a private function called by _add_default_upsamplers().

Parameters:	ini_ups (dict) – upsamplers for the specified `.ini` file

new._std_nonint_ewa_lin_flt_mtds(ini_ups)[source]¶

Add the standard non-interpolatory EWA linear filtering methods.

Note

This is a private function called by _add_default_upsamplers().

Parameters:	ini_ups (dict) – upsamplers for the specified `.ini` file

new._std_nonint_lin_tensor_mtds(ini_ups)[source]¶

Add the standard non-interpolatory linear tensor methods.

Note

This is a private function called by _add_default_upsamplers().

Parameters:	ini_ups (dict) – upsamplers for the specified `.ini` file

new.main()[source]¶

Run exquires-new.

Create a project file to use with exquires-run and exquires-update.

The `operations` Module¶

A collection of classes used to compute image difference data.

The hierarchy of classes is as follows:

Operations encapsulate a list of Images

Images encapsulate a dict of images and a list of Downsamplers

Downsamplers encapsulate a dict of downsamplers and a list of Ratios

Ratios encapsulate a dict of ratios and a list Images

Images encapsulate a dict of images and a dict of metrics

These classes work together to downsample the master images, upsample the downsampled images, and compare the upsampled images to the master images. To perform the operations, call Operations.compute().

The `Operations` Class¶

class operations.Operations(images)[source]¶

Bases: object

A collection of Image objects to compute data with.

This class is responsible for calling all operations defined in the specified project file when using exquires-run or exquires-update.

Parameters:	images (list of `Images`) – images to downsample

compute(args, old=None)[source]¶

Perform all operations.

Parameters:

args (argparse.Namespace) – arguments
args.prog (string) – name of the calling program
args.dbase_file (path) – database file
args.proj (string) – name of the current project
args.silent (boolean) – True if using silent mode
args.met_same (dict) – unchanged metrics
args.metrics (dict) – current metrics
args.config_file (path) – current configuration file
args.config_bak (path) – previous configuration file
old (argparse.Namespace) – old configuration entries to be removed

The `Images` Class¶

class operations.Images(images, downsamplers, same=False)[source]¶

Bases: object

This class calls operations for a particular set of images.

Parameters:	images (dict) – images to downsample downsamplers (list of `Downsamplers`) – downsamplers to use same (boolean) – True if using unchanged images

compute(args)[source]¶

Perform all operations for this set of images.

Parameters:

args (argparse.Namespace) – arguments
args.dbase_file (path) – database file
args.dbase (database.Database) – connected database
args.proj (string) – name of the current project
args.silent (boolean) – True if using silent mode
args.met_same (dict) – unchanged metrics
args.metrics (dict) – current metrics
args.do_op (function) – updates the displayed progress

The `Downsamplers` Class¶

class operations.Downsamplers(downsamplers, ratios, same=False)[source]¶

Bases: object

This class calls operations for a particular set of downsamplers.

Parameters:	downsamplers (dict) – downsamplers to use ratios (list of `Ratios`) – ratios to downsample by same (boolean) – True if using unchanged downsamplers

compute(args, same)[source]¶

Perform all operations for this set of downsamplers.

Parameters:

args (argparse.Namespace) – arguments
args.dbase_file (path) – database file
args.dbase (database.Database) – connected database
args.proj (string) – name of the current project
args.silent (boolean) – True if using silent mode
args.met_same (dict) – unchanged metrics
args.metrics (dict) – current metrics
args.do_op (function) – updates the displayed progress
args.image (string) – name of the image
args.image_dir (path) – directory to store results for this image
args.master (path) – master image to downsample
same (boolean) – True if possibly accessing an existing table

The `Ratios` Class¶

class operations.Ratios(ratios, upsamplers, same=False)[source]¶

Bases: object

This class calls operations for a particular set of ratios.

Parameters:	ratios (dict) – ratios to downsample by upsamplers (list of `Upsamplers`) – upsamplers to use same (boolean) – True if using unchanged ratios

compute(args, downsamplers, same)[source]¶

Perform all operations for this set of ratios.

Parameters:

args (argparse.Namespace) – arguments
args.dbase_file (path) – database file
args.dbase (database.Database) – connected database
args.proj (string) – name of the current project
args.silent (boolean) – True if using silent mode
args.met_same (dict) – unchanged metrics
args.metrics (dict) – current metrics
args.do_op (function) – updates the displayed progress
args.image (string) – name of the image
args.image_dir (path) – directory to store results for this image
args.master (path) – master image to downsample
args.downsampler (string) – name of the downsampler
args.downsampler_dir (path) – directory to store dowsampled images
downsamplers (dict) – downsamplers to use
same (boolean) – True if accessing an existing table

The `Upsamplers` Class¶

class operations.Upsamplers(upsamplers, metrics, same=False)[source]¶

Bases: object

This class upsamples an image and compares with its master image.

Parameters:	upsamplers (dict) – upsamplers to use metrics (dict) – metrics to compare with same (boolean) – True if using unchanged upsamplers

compute(args, same)[source]¶

Perform all operations for this set of ratios.

Parameters:

args (argparse.Namespace) – arguments
args.dbase_file (path) – database file
args.dbase (database.Database) – connected database
args.proj (string) – name of the current project
args.silent (boolean) – True if using silent mode
args.met_same (dict) – unchanged metrics
args.metrics (dict) – current metrics
args.do_op (function) – updates the displayed progress
args.image (string) – name of the image
args.image_dir (path) – directory to store results for this image
args.master (path) – master image to downsample
args.downsampler (string) – name of the downsampler
args.downsampler_dir (path) – directory to store dowsampled images
args.ratio (string) – resampling ratio
args.small (path) – downsampled image
args.table (string) – name of the table to insert the row into
args.table_bak (string) – name of the backup table (if it exists)
same (boolean) – True if accessing an existing table

The `parsing` Module¶

Classes and methods used for parsing arguments and formatting help text.

parsing._format_doc(docstring)[source]¶

Parse the module docstring and re-format all reST markup.

Note

This is a private function called when creating a new ExquiresParser object.

Parameters:	docstring (string) – docstring to format
Returns:	formatted docstring
Return type:	string

parsing._remove_duplicates(input_list)[source]¶

Remove duplicate entries from a list.

Note

This is a private function called by ListAction.__call__() and RatioAction.__call__().

Parameters:	input_list (list of values) – list to remove duplicate entries from
Returns:	list with duplicate entries removed
Return type:	list of values

The `ExquiresParser` Class¶

class parsing.ExquiresParser(description)[source]¶

Bases: argparse.ArgumentParser

Generic EXQUIRES parser.

Parameters:	description (string) – docstring from the calling program

parse_args(args=None, namespace=None)[source]¶

Parse command-line arguments.

Parameters:	args (string) – the command-line arguments namespace (`argparse.Namespace`) – the namespace
Returns:	the parsed arguments
Return type:	`argparse.Namespace`

The `OperationsParser` Class¶

class parsing.OperationsParser(description, update=False)[source]¶

Bases: parsing.ExquiresParser

Parser used by exquires-run and exquires-update.

Parameters:	description (string) – docstring from the calling program update (boolean) – True if called by exquires-update

parse_args(args=None, namespace=None)[source]¶

Parse the received arguments.

This method parses the arguments received by exquires-run or :ref`exquires-update`.

Parameters:	args (string) – the command-line arguments namespace (`argparse.Namespace`) – the namespace
Returns:	the parsed arguments
Return type:	`argparse.Namespace`

The `StatsParser` Class¶

class parsing.StatsParser(description, correlate=False)[source]¶

Bases: parsing.ExquiresParser

Parser used by exquires-report and exquires-correlate.

Parameters:	description (string) – docstring from the calling program correlate (boolean) – True if using exquires-correlate

parse_args(args=['-b', 'html', '-d', '_build/doctrees', '.', '_build/html'], namespace=None)[source]¶

Parse the received arguments.

This method parses the arguments received by exquires-report or exquires-correlate.

Parameters:	args (string) – the command-line arguments namespace (`argparse.Namespace`) – the namespace
Returns:	the parsed arguments
Return type:	`argparse.Namespace`

The `ExquiresHelp` Class¶

class parsing.ExquiresHelp(prog, indent_increment=2, max_help_position=24, width=None)[source]¶

Bases: argparse.RawDescriptionHelpFormatter

Formatter for generating usage messages and argument help strings.

This class is designed to display options in a cleaner format than the standard argparse help strings.

_fill_text(text, width, indent)[source]¶

Fill action text with whitespace.

Parameters:	text (string) – the text to display width (integer) – line width indent (string) – indentation printed before the text
Returns:	the formatted text
Return type:	string

_format_action_invocation(action)[source]¶

Format the string describing the invocation of the specified action.

Parameters:	action (`argparse.Action`) – the parsing action
Returns:	the formatted action invocation
Return type:	string

The `ProjectAction` Class¶

class parsing.ProjectAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶

Bases: argparse.Action

Parser action to read a project file based on the specified name.

__call__(parser, args, value, option_string=None)[source]¶

Parse the -p/--project option.

Parameters:	parser (`ExquiresParser`) – the parser calling this action args (`argparse.Namespace`) – arguments values (list of values) – values option_string (string) – command-line option string
Raises :	`argparse.ArgumentError`

The `ListAction` Class¶

class parsing.ListAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶

Bases: argparse.Action

Parser action to handle wildcards for options that support them.

When specifying aggregation options with exquires-report, this class expands any wildcards passed in arguments for the following options:

Images
Downsamplers
Upsamplers
Metrics

__call__(parser, args, values, option_string=None)[source]¶

Parse any option that supports lists with wildcard characters.

Parameters:	parser (`ExquiresParser`) – the parser calling this action args (`argparse.Namespace`) – arguments values (list of values) – values option_string (string) – command-line option string
Raises :	`argparse.ArgumentError`

The `RatioAction` Class¶

class parsing.RatioAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶

Bases: argparse.Action

Parser action to deal with ratio ranges.

__call__(parser, args, values, option_string=None)[source]¶

Parse the -r/--ratio option.

Parameters:	parser (`ExquiresParser`) – the parser calling this action args (`argparse.Namespace`) – arguments values (list of values) – values option_string (string) – command-line option string
Raises :	`argparse.ArgumentError`

The `AnchorAction` Class¶

class parsing.AnchorAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶

Bases: argparse.Action

Parser action to sort the correlation matrix.

__call__(parser, args, value, option_string=None)[source]¶

Parse the -a/--anchor option.

Parameters:	parser (`ExquiresParser`) – the parser calling this action args (`argparse.Namespace`) – arguments values (list of values) – values option_string (string) – command-line option string
Raises :	`argparse.ArgumentError`

The `SortAction` Class¶

class parsing.SortAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]¶

Bases: argparse.Action

Parser action to sort the data by the appropriate metric.

__call__(parser, args, value, option_string=None)[source]¶

Parse the -s/--sort option.

Parameters:	parser (`ExquiresParser`) – the parser calling this action args (`argparse.Namespace`) – arguments values (list of values) – values option_string (string) – command-line option string
Raises :	`argparse.ArgumentError`

The `progress` Module¶

Display progress info for exquires-run and exquires-update.

When the -s/--silent option is not selected in exquires-run or exquires-update, the Progress class is used to display the appropriate information.

The `Progress` Class¶

class progress.Progress(program, proj, total_ops)[source]¶

Bases: object

This class contains methods for displaying progress in exquires.

When exquires-run and exquires-update are used without silent mode enabled, this class is responsible for displaying information about the downsampling, upsampling, and comparison steps and the total progress.

Parameters:	program (string) – name of the program that is running proj (string) – name of the project being used total_ops (integer) – total number of operations

_Progress__table_bottom(line, label, content)¶

Draw the bottom row of the progress table.

This method draws one of the middle rows of the progress table. Two lines are used to draw this section of the table.

Note

This is a private method called by cleanup(), complete(), and do_op().

Warning

To display the updated progress table, the screen must be refreshed by calling self.scr.refresh().

Parameters:	line (integer) – line number to start drawing at label (string) – label for this table entry content (string) – content for this table entry

_Progress__table_middle(line, label, content)¶

Draw one of the middle rows of the progress table.

This method draws one of the middle rows of the progress table. Two lines are used to draw this section of the table.

Note

This is a private method called by cleanup(), complete(), and do_op().

Warning

To display the updated progress table, the screen must be refreshed by calling self.scr.refresh().

Parameters:	line (integer) – line number to start drawing at label (string) – label for this table entry content (string) – content for this table entry

_Progress__table_top(line, label, content)¶

Draw the top row of the progress table.

This method draws the first row of the progress table, which displays the project name. Three lines are used to draw this section of the table.

Note

This is a private method called by cleanup(), complete(), and do_op().

Warning

To display the updated progress table, the screen must be refreshed by calling self.scr.refresh().

Parameters:	line (integer) – line number to start drawing at label (string) – label for this table entry content (string) – content for this table entry

cleanup()[source]¶: Indicate that files are being deleted.

complete()[source]¶

Complete the progress indicator.

Call this method to indicate success once all operations have been performed.

Note

The completion screen is displayed for a half second.

Warning

To restore the terminal after completion, destruct the Progress object by calling del prg (where prg is the object to destruct).

do_op(args, upsampler=None, metric=None)[source]¶

Update the progress indicator.

If no upsampler is specified, operation=downsampling
If an upsampler is specified, but no metric, operation=upsampling
If an upsampler and metric are specified, operation=comparing

Parameters:	args (`argparse.Namespace`) – arguments args.image (string) – image being processed args.downsampler (string) – downsampler being used args.ratio (string) – resampling ratio being used upsampler (string) – upsampler being used metric (string) – metric being used

The `report` Module¶

Print a formatted table of aggregate image difference data.

Each database table in the current project contains data for a single image, downsampler, and ratio. Each row represents an upsampler and each column represents a difference metric. By default, the data across all rows and columns of all tables is aggregated. Use the appropriate option flags to aggregate across a subset of the database.

Features:

-R/:option`–ratio` supports hyphenated ranges (for example, ‘1-3 5’ gives ‘1 2 3 5’)

-U/--up, -I/--image, -D/--down and -M/--metric support wildcard characters

report._print_table(args)[source]¶

Print a table of aggregate image comparison data.

Since the database contains error data for several images, downsamplers, ratios, upsamplers, and metrics, it is convenient to be able to specify which of these to consider. This method aggregates the data for each relevant column in the appropriate tables.

Note

This is a private function called by main().

Parameters:

args (argparse.Namespace) – arguments
args.dbase_file (path) – database file
args.image (list of strings) – selected image names
args.down (list of strings) – selected downsampler names
args.ratio (list of strings) – selected ratios
args.up (list of strings) – selected upsampler names
args.metric (list of strings) – selected metric names
args.metrics_d (dict) – all metric names
args.file (path) – output file
args.digits (integer) – number of digits to print
args.latex (boolean) – True if printing a LaTeX-formatted table
args.rank (boolean) – True if printing Spearman (fractional) ranks
args.merge (boolean) – True if printing merged Spearman ranks
args.sort (string) – metric to sort by
args.show_sort (boolean) – True if the sort column should be displayed

report.main()[source]¶

Run exquires-report.

Parse the command-line arguments and print the aggregate data table.

The `run` Module¶

Compute error data for the entries in the specified project file.

The project file is read to determine which images, downsamplers, ratios, upsamplers, and metrics to use. If a database file already exists for this project, it will be backed up and a new one will be created.

Each image will be downsampled by each of the ratios using each of the downsamplers. The downsampled images will then be upsampled back to their original size (840x840) using each of the upsamplers. The upsampled images will be compared to the original images using each of the metrics and the results will be stored in the database file.

If you make changes to the project file and wish to only compute data for these changes rather than recomputing everything, use exquires-update.

To view aggregated error data, use exquires-report.

run._run(args)[source]¶

Create a new project database and populate it with computed data.

Note

This is a private function called by main().

Parameters:	args (`argparse.Namespace`) – arguments args.config_file (path) – current configuration file

run.main()[source]¶

Run exquires-run.

Create a database for the specified project file.

Warning

If a database already exists for this project, it will be overwritten.

The `stats` Module¶

A collection of methods for producing statistical output.

stats._format_cell(cell, digits)[source]¶

Return a formatted version of this cell of the data table.

Note

This is a private function called by print_normal() and print_latex().

Parameters:	cell (string) – cell to format digits (integer) – maximum number of digits to display
Returns:	the formatted cell
Return type:	string

stats.get_aggregate_table(dbase, upsamplers, metrics_d, tables)[source]¶

Return a table of aggregate image difference data.

Parameters:	dbase (`database.Database`) – connected database upsamplers (list of strings) – upsamplers (rows) of the table metrics_d (dict) – metrics (columns) of the table in dictionary form tables (list of strings) – names of database tables to aggregate across
Returns:	table of aggregate image difference data
Return type:	list of lists

stats.get_merged_ranks(printdata, metrics_desc, sort_index)[source]¶

Return a table of merged Spearman ranks based on a data table.

Parameters:	printdata (list of lists) – table of data to print metrics_desc (list of integers) – list of 0s and 1s (where 1 is ‘descending’) sort_index (integer) – index of the column to sort by
Returns:	table of merged ranks
Return type:	list of lists

stats.get_ranks(printdata, metrics_desc, sort_index)[source]¶

Return a table of Spearman (Fractional) ranks based on a data table.

Parameters:	printdata (list of lists) – table of data to print metrics_desc (list of integers) – list of 0s and 1s (where 1 is ‘descending’) sort_index (integer) – index of the column to sort by
Returns:	table of ranks
Return type:	list of lists

stats.print_latex(printdata, args, header, matrix=False)[source]¶

Print the processed data table with LaTeX formatting.

Parameters:	printdata (list of lists) – table of data to print args (`argparse.Namespace`) – arguments args.file (path) – path to write the aggregated error table args.digits (integer) – maximum number of digits to display header (list of strings) – table headings matrix (boolean) – True if printing a correlation matrix

stats.print_normal(printdata, args, header, matrix=False)[source]¶

Print the processed data table with normal formatting.

Parameters:	printdata (list of lists) – table of data to print args (`argparse.Namespace`) – arguments args.file (path) – path to write the aggregated error table args.digits (integer) – maximum number of digits to display header (list of strings) – table headings matrix (boolean) – True if printing a correlation matrix

The `tools` Module¶

A collection of convenience methods.

tools.create_dir(base_dir, relative_dir='')[source]¶

Create a directory if it doesn’t already exist and return it.

Parameters:	base_dir (path) – base directory within which to create the directory relative_dir (path) – directory to create inside the base directory
Returns:	the created directory
Return type:	path

tools.prune_metrics(keys, metrics_d)[source]¶

Prune a dictionary of metrics using a list of keys.

Parameters:	keys (list of strings) – keys to retain metrics_d (dict) – metrics to prune
Returns:	pruned metrics
Return type:	dict

The `update` Module¶

Compute new error data for changes to the user-specified project file.

The project file is inspected to determine which changes have been made. Items that have been removed will result in entries being removed from the database. Items that have been changed or added will result in new data being computed and added to the database file. If no changes have been made to the project file, the database will not be updated.

If you wish to recompute all data based on your project file rather than simply updating it with the changes, use exquires-run.

To view aggregated error data, use exquires-report.

update._get_namespaces(config_file, config_bak)[source]¶

Return all necessary configuration namespaces.

This function returns four namespaces that specify which images, downsamplers, ratios, upsamplers, and metrics to use when creating or updating a project database:

current – all entries in current project file
new – entries only in currenty project file
old – entries only in previous project file
same – entries common to both project files

Note

This is a private function called by _update().

Parameters:	config_file (path) – current configuration file config_bak (path) – previous configuration file
Returns:	the current, new, old, and same namespaces
Return type:	`argparse.Namespace`

update._subtract(dict1, dict2)[source]¶

Subtract dictionary dict2 from dict1 and return the difference.

This function creates a new dict, then iterates over dict1 and adds all entries that are not found in dict2.

Note

This is a private function called by _get_namespaces().

Parameters:	dict1 (dict) – dictionary to subtract from dict2 (dict) – dictionary to subtract
Returns:	dict1 - dict2
Return type:	dict

update._update(args)[source]¶

Update the database.

Note

This is a private function called by main().

Parameters:	args (`argparse.Namespace`) – arguments args.config_file (path) – current project file args.config_bak (path) – previous project file

update.main()[source]¶

Run exquires-update.

Update the project database based on changes to the project file.

Note

If the update fails, the previous database will be restored.

Modules & Classes¶

The `aggregate` Module¶

The `Aggregate` Class¶

The `compare` Module¶

The `Metrics` Class¶

The `correlate` Module¶

The `database` Module¶

The `Database` Class¶

The `new` Module¶

The `operations` Module¶

The `Operations` Class¶

The `Images` Class¶

The `Downsamplers` Class¶

The `Ratios` Class¶

The `Upsamplers` Class¶

The `parsing` Module¶

The `ExquiresParser` Class¶

The `OperationsParser` Class¶

The `StatsParser` Class¶

The `ExquiresHelp` Class¶

The `ProjectAction` Class¶

The `ListAction` Class¶

The `RatioAction` Class¶

The `AnchorAction` Class¶

The `SortAction` Class¶

The `progress` Module¶

The `Progress` Class¶

The `report` Module¶

The `run` Module¶

The `stats` Module¶

The `tools` Module¶

The `update` Module¶

Table Of Contents

Previous topic

Next topic

This Page

NAME	DESCRIPTION
l_1	return the average
l_2	average the squares and return the square root
l_4	average the quads and return the fourth root
l_inf	return the maximum

NAME	DESCRIPTION
srgb_1	$\ell_1$ norm in sRGB colour space
srgb_2	$\ell_2$ norm in sRGB colour space
srgb_4	$\ell_4$ norm in sRGB colour space
srgb_inf	$\ell_\infty$ norm in sRGB colour space
cmc_1	$\ell_1$ norm using the CMC(1:1) colour difference
cmc_2	$\ell_2$ norm using the CMC(1:1) colour difference
cmc_4	$\ell_4$ norm using the CMC(1:1) colour difference
cmc_inf	$\ell_\infty$ norm using the CMC(1:1) colour difference
xyz_1	$\ell_1$ norm in XYZ colour space
xyz_2	$\ell_2$ norm in XYZ colour space
xyz_4	$\ell_4$ norm in XYZ colour space
xyz_inf	$\ell_\infty$ norm in XYZ colour space
blur_1	MSSIM-inspired $\ell_1$ norm
blur_2	MSSIM-inspired $\ell_2$ norm
blur_4	MSSIM-inspired $\ell_4$ norm
blur_inf	MSSIM-inspired $\ell_\infty$ norm
mssim	Mean Structural Similarity Index (MSSIM)

Navigation

Modules & Classes¶

The aggregate Module¶

The Aggregate Class¶

The compare Module¶

The Metrics Class¶

The correlate Module¶

The database Module¶

The Database Class¶

The new Module¶

The operations Module¶

The Operations Class¶

The Images Class¶

The Downsamplers Class¶

The Ratios Class¶

The Upsamplers Class¶

The parsing Module¶

The ExquiresParser Class¶

The OperationsParser Class¶

The StatsParser Class¶

The ExquiresHelp Class¶

The ProjectAction Class¶

The ListAction Class¶

The RatioAction Class¶

The AnchorAction Class¶

The SortAction Class¶

The progress Module¶

The Progress Class¶

The report Module¶

The run Module¶

The stats Module¶

The tools Module¶

The update Module¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation

The `aggregate` Module¶

The `Aggregate` Class¶

The `compare` Module¶

The `Metrics` Class¶

The `correlate` Module¶

The `database` Module¶

The `Database` Class¶

The `new` Module¶

The `operations` Module¶

The `Operations` Class¶

The `Images` Class¶

The `Downsamplers` Class¶

The `Ratios` Class¶

The `Upsamplers` Class¶

The `parsing` Module¶

The `ExquiresParser` Class¶

The `OperationsParser` Class¶

The `StatsParser` Class¶

The `ExquiresHelp` Class¶

The `ProjectAction` Class¶

The `ListAction` Class¶

The `RatioAction` Class¶

The `AnchorAction` Class¶

The `SortAction` Class¶

The `progress` Module¶

The `Progress` Class¶

The `report` Module¶

The `run` Module¶

The `stats` Module¶

The `tools` Module¶

The `update` Module¶