src module

Core implementation of the serial and faceted SARA dictionary (based on [Prusa2012] for the faceted version).

src.col(x)

Reshape array as a column vector.

Reshape any input array/matrix as a column vector.

Parameters

x (array) – Input array.

Returns

Vectorized form (column-major ordering) of the input array.

Return type

array

src.comm2d_reduce(x_overlap, overlap_size, Qy, Qx)

Reduce overlapping borders between contiguous facets (2D).

Additive reduction of the duplicated area (overlap regions) for a 2D image tessellation (2D communication grid).

Parameters

• x_overlap (double[:, :]) – Spatial facet considered (with overlap).

• overlap_size (int[2, 1]) – Size of the left and top facet extensions [2,1].

• Qy (int) – Number of spatial facets along the y axis.

• Qx (int) – Number of spatial facets along the x axis.

Returns

x_overlap – Updated spatial facet.

Return type

double[:, :]

src.comm2d_reduce_wideband(x_overlap, overlap_size, Qy, Qx, Qc)

Reduce overlapping borders between contiguous facets (2D).

Additive reduction of the duplicated area (overlap regions) for a 2D image tessellation (2D communication grid).

Parameters

• x_overlap (double[:, :, :]) – Spatial facet considered (with overlap).

• overlap_size (int[2, 1]) – Size of the left and top facet extensions [2,1].

• Qy (int) – Number of spatial facets (along the y axis).

• Qx (int) – Number of spatial facets (along the x axis).

• Qc (int) – Number of spectral facets (along the z axis).

Returns

x_overlap – Updated spatial facet.

Return type

double[:, :, :]

src.comm2d_update_borders(x_overlap, overlap_size, overlap_south_east, overlap_south, overlap_east, Qy, Qx)

Update facet overlap (2D image tessellation and communication grid).

Update the overlapping regions between contiguous facets based on a 2D image tessellation (2D communication grid).

Parameters

• x_overlap (double[:, :, :]) – Spatial facet considered (with overlap).

• overlap_size (int[2,1]) – Size of the left and top facet extensions [2,1].

• overlap_south_east (int[2,1]) – Size of the overlap for the south-east neighbour [2,1]

• overlap_south (int[2,1]) – Size of the overlap for the northern neighbour [2,1].

• overlap_east (int[2,1]) – Size of the overlap for the eastern neighbour [2,1].

• Qy (int) – Number of spatial facets along the y axis.

• Qx (int) – Number of spatial facets along the x axis.

Returns

x_overlap – Spatial facet with updated borders.

Return type

double[:, :, :]

src.comm2d_update_borders_wideband(x_overlap, overlap_size, overlap_south_east, overlap_south, overlap_east, Qy, Qx, Qc)

Update facet overlap (2D image tessellation and communication grid).

Update the overlapping regions between contiguous facets based on a 2D image tessellation (2D communication grid).

Parameters

• x_overlap (double[:, :, :]) – Spatial facet considered (with overlap).

• overlap_size (int[2,1]) – Size of the left and top facet extensions [2,1].

• overlap_south_east (int[2,1]) – Size of the overlap for the south-east neighbour [2,1].

• overlap_south (int[2,1]) – Size of the overlap for the northern neighbour [2,1].

• overlap_east (int[2,1]) – Size of the overlap for the eastern neighbour [2,1].

• Qy (int) – Number of spatial facets along the y axis.

• Qx (int) – Number of spatial facets along the x axis.

• Qc (int) – Number of spectral facets along the z axis.

Returns

x_overlap – Spatial facet with updated borders.

Return type

double[:, :, :]

src.compute_size(I, dims, J, status, L)

Compute the number of wavelet coefficients generated for a facet.

Compute the number of wavelet coefficients generated for one facet by the faceted wavelet transform described in [Prusa2012].

Parameters

• I (int[2]) – Facet start index [1,2].

• dims (int[2]) – Dimension of the current facet (w/o overlap) .

• J (int) – Number of decomposition levels.

• status (array) – Status of the facet (first/last) [1,2] value {-1, 0, 1, Nan} for (first, none, last, both).

• L (int) – Length of the filter involved in the wavelet decomposition.

Returns

• dims_PsitLx_crop (int[:, :]) – Dimension of the wavelet coefficients at each stage of the transform. [J+1,2]

• Ncoefs (int[:, :]) – Number of valid coefficients. [J+1,2]

• Ij (int[:, :]) – Start index (in the global image) of the facet needed to compute the jth level of the wavelet decomposition. [J+1,2]

src.generate_weights(qx, qy, Qx, Qy, window_type, dims, dims_o, d, varargin)

Generate the weighting matrix for a single facet.

Generate the weighting matrix of a single facet invlved in the faceted nuclear norm term.

Parameters

• qx (int) – Facet index along axis x.

• qy (int) – Facet index along axis y.

• Qx (int) – Number of facets along axis x.

• Qy (int) – Number of facets along axis y.

• window_type (string) – Name of the window considered. Possible values: 'triangular', 'hamming', 'pc' (piecewise constant).

• dims (int[2, 1]) – Size of the tile (w/o overlap) [2, 1].

• dims_o (int[2, 1]) – Dimension of the facet [2, 1].

• d (int[2, 1]) – Number of pixels in the overlap along each direction [2, 1].

• varargin (double) – Minimum value for the triangular window (only active in this case).

src.get_overlap_size(N, Q, overlap_fraction)

Convert fraction of overlap into the corresponding number of pixels.

Compute the number of pixels corresponding to a prescribed overlap fraction (specified relatively to the size of the overlapping facet).

Parameters

• N (int[2]) – Size of the full image [1, 2].

• Q (int[2]) – Number of facets along each dimension [1, 2].

• overlap_fraction (array, double) – Overlap fraction between two consecutive facets, given along each dimension (fraction expressed with respect to the final facet size).

Raises

AssertionError – All entries in overlap_fraction need to be strictly lower than 0.5 (only overlap between consecutive facets is supported).

Returns

overlap_size – Number of pixels contained in the overlap region.

Return type

int[2]

src.isdwt2(SPsitLx, I, dims, Ncoefs, lo, hi, J, pre_offset, post_offset)

Inverse facet wavelet transform.

Inverse operator to compute the contribution of a single facet to the full wavelet transform.

Parameters

• SPsitLx (double[:]) – Wavelet coefficients obtained from the facet of interest.

• I (int[2]) – Starting index of the tile (no overlap) [1,2].

• dims (int[2]) – dimension of tbe underlying tile (no overlap) [1,2].

• Ncoefs (int[:, :]) – Dimension of the wavelet facets for each level of the decomposition level, for each dictionary [M(J+1),2] {from level 1 to J}.

• lo (array) – Low-pass synthesis wavelet filter. [1,L]

• hi (array) – High-pass synthesis wavelet filter. [1,L]

• J (int) – Number of decomposition levels considered.

• pre_offset (int[2]) – Number of coefficients to be cropped from the start of the reconstructed facet [1,2].

• post_offset (int[2]) – Number of coefficients to be cropped at the end of the reconstructed facet [1,2].

Returns

PsiSty – Inverse transform of the input matrix.

Return type

array

src.isdwt2_faceting(SPsitLx, I, dims, Ncoefs, wavelet, J, left_offset, right_offset)

Inverse facet wavelet transform for a single wavelet dictionary.

Parameters

• SPsitLx (array[:]) – Wavelet coefficients.

• I (int[2]) – Facet start index [1, 2].

• dims (int[2]) – Dimension of the current facet (w/o overlap).

• Ncoefs (int[J+1, 1]) – Number of wavelet coefficients obtained at each scale. [J+1, 1].

• wavelet (string) – Name of the wavelet dictionary considered.

• J (int) – Number of decomposition levels considered.

• left_offset (int[1, 2]) – Number of coefficients to be cropped from the left of the reconstructed facet [1, 2].

• right_offset (int[1, 2]) – Number of coefficients to be cropped from the right of the reconstructed facet [1, 2].

Returns

PsiSty – Image facet (with overlap).

Return type

array[:, :]

src.isdwt2_sara(SPsitLx, I, dims, I_overlap, dims_overlap, Ncoefs, J, wavelet, pre_offset_dict, post_offset_dict)

Inverse facet SARA operator.

Inverse operator to compute the contribution of the SARA prior to a single facet.

Parameters

• SPsitLx (array[:]) – Wavelet coefficients obtained from the facet of interest.

• I (int[2]) – Starting index of the tile (no overlap) [1,2].

• dims (int[2]) – Tile dimension (no overlap) [1,2].

• I_overlap (int[2]) – Starting index of the facet (including overlap) [1,2].

• dims_overlap (int[:, :]) – Dimension of the extended image facets (including overlap) [M,2].

• Ncoefs (int[:, :]) – Dimension of the wavelet facets for each level of the decomposition level, for each dictionary [M(J+1),2] {from level 1 to J}.

• J (int) – Number of decomposition levels considered.

• wavelet (cell{1, :} of string) – Name of the wavelet dictionaries considered {M,1}.

• pre_offset_dict (int[:, :]) – Number of coefficients to be cropped from the start of the reconstructed facet [M,2].

• post_offset_dict (int[:, :]) – Number of coefficients to be cropped from the end of the reconstructed facet [M,2].

Returns

PsiSty – inverse transform of the input matrix.

Return type

array

src.isdwt2_sara_faceting(SPsitLx, I, dims, I_overlap, dims_overlap, Ncoefs, J, wavelet, left_offset, right_offset)

Inverse facet SARA operator (simplified version for faceting code).

Inverse operator to compute the contribution of the SARA prior to a single facet.

Parameters

• SPsitLx (array[:]) – Wavelet coefficients obtained from the facet of interest.

• I (int[2]) – Starting index of the facet (without overlap) [1,2].

• dims (int[2]) – Facet dimension (without overlap) [1,2].

• I_overlap (int[2]) – Starting index of the facet (including overlap) [1,2].

• dims_overlap (int[:, :]) – Dimension of the extended image facets (including overlap) [M,2].

• Ncoefs (int[:, :]) – Dimension of the wavelet facets for each level of the decomposition level, for each dictionary [M(J+1),2] {from level 1 to J}.

• J (int) – Number of decomposition levels considered.

• wavelet (cell{1, :} of string) – Name of the wavelet dictionaries considered {M,1}.

• left_offset (int[:, :]) – Number of coefficients to be cropped from the left of the reconstructed facet [M,2].

• right_offset (int[:, :]) – Number of coefficients to be cropped from the right of the reconstructed facet [M,2].

Returns

PsiSty – Inverse transform of the input matrix.

Return type

array

src.local_split_range(nchunks, N, index, varargin)

Returns the indices delimiting the portion of 1:N in position index.

Tessellates 1:N into (non-)overlapping subsets, each containing approximately the same number of indices, following the decomposition rules specified in varargin. Returns only the first and last indices corresponding to the chunk in position index.

Parameters

• nchunks (int) – Number of segments.

• N (int) – Number of indices.

• index (int) – Position of the chunk considered.

• varargin (int) – Defines the amount of pixels in the overlap between consecutive segments (if any).

Returns

rg – First/last index of the segment in position index [1, 2].

Return type

int[nchunks, 2]

src.n_wavelet_coefficients(m, N, extension_mode, nlevel)

Compute number of wavelet coefficients.

Determine the number of wavelet coefficients resulting from a 2D decomposition by a filter of length m [1, 2] (2D), for a given type of boundary conditions and number of decomposition levels.

Parameters

• m (int[:]) – Size of the considered filters [K, 1] (1 per type of dictionary).

• N (int[2]) – Image dimension [1, 2].

• extension_mode (string) – Type of boundary extension (‘per’, ‘zpd’, ‘sym’).

• nlevel (int) – Number of decomposition level.

Returns

• dims (int[:, 2]) – Size of the coefficients at each level of the decomposition [nlevel+1,2].

• s (int) – Total number of wavelet coefficients.

src.op_p_sp_wlt_basis(basis, nlevel, Ny, Nx)

Resturns the operator to the sparsity wavelet basis passed as argument Each basis is considered to be distributed to a different node.

Parameters

• basis (cell[string]) – Cell of strigs containing the names of the wavelets to be used, eg: {‘db1’, ‘db2’, ‘self’}.

• nlevel (int) – Decomposition level.

• Ny (int) – Image size.

• Nx (int) – Flag to reset the sizes used for reconstruction.

Returns

• Psi (cell{anonymous functions}) – Function handles for direct operator.

• Psit (cell{anonymous function}) – Function handles for adjoint operator.

src.op_sp_wlt_basis(basis, nlevel, Ny, Nx)

Resturns anynomous functions corresponding to the sparsity wavelet basis SARA [Carrillo2012] specified from the wavelets taken in basis.

Parameters

• basis (cell (strings)) – Cell of strings with the names of the wavelets to be used.

• nlevel (int) – Number of decomposition levels.

• Ny (int) – Image size (axis 1).

• Nx (int) – Image size (axis 2).

Returns

• Psi (anonymous function) – Anonymous function implementating the direct SARA operator.

• Psit (anonymous function) – Anonymous function implementating the inverse SARA operator.

Example

>>> basis = {'db1', 'db2', 'self'};
>>> nlevel = 2;
>>> Ny = 128;
>>> Nx = 128;
>>> [Psi, Psit] = op_sp_wlt_basis(basis, nlevel, Ny, Nx);

src.place2DSegment(im, PsiSty, I_facet_min, dims_facet_max)

Recombine image coefficients coming from the inverse faceted wavelet transform of a single facet back into a full-size image (exclusively used for testing and debugging purposes).

Parameters

• im (array[:, :]) – Input image.

• PsiSty (array[:]) – Coefficients associated to a given facet.

• I_facet_min (int[2, 1]) – Starting index of the associated image facet.

• dims_facet_max – Dimension of the image facet.

Returns

im – Updated image.

Return type

array[:, :]

src.sdwt2(x_overlap, dims, status, lo, hi, J, Ncoefs)

Forward facet wavelet transform.

Forward operator to compute the contribution of the a single input facet to the whole wavelet transform.

Parameters

• x_overlap (array[:, :]) – Image facet (with overlap).

• dims (int[2]) – Dimensions of the underlying image tile. [1,2].

• status (int[2]) – Indicates whether the facet is the first (or the last) along each dimension. [1,2] (first: -1, last: 1, none: 0, or both: NaN)).

• lo (array[1, :]) – Low-pass analysis wavelet filter. [1,L]

• hi (array[1, :]) – High-pass analysis wavelet filter. [1,L]

• J (int) – Number of decomposition levels considered.

• Ncoefs (int[:]) – Number of wavelet coefficients obtained at each scale. [J+1,1]

Returns

SPsitLx – Associated wavelet coefficients.

Return type

array[:, :]

src.sdwt2_faceting(imApprox, status, wavelet, J, Ncoefs)

Forward facet wavelet transform.

Forward operator to compute the contribution of the a single input facet to the whole wavelet transform.

Parameters

• imApprox (array[:, :]) – Image facet (with overlap).

• status (array) – Indicates whether the facet is the first (or the last) along each dimension. [1,2] (first: -1, last: 1, none: 0, or both: NaN)).

• wavelet (string) – Name of the wavelet dictionary.

• J (int) – Number of decomposition levels considered.

• Ncoefs (int[J]) – Number of wavelet coefficients obtained at each scale. [J+1,1]

Returns

SPsitLx – Associated wavelet coefficients.

Return type

array[:]

src.sdwt2_max_nfacets(N, nlevel, filter_length)

Maximum number of facets admissible for the faceted wavelet transform.

Returns the maximum admissible number of facets so that the overlap required by the faceted wavelet transform does not exceed the size of a tile (i.e., tessellation of 1:N into non-overlapping subsets of successive integers).

Parameters

• N (int) – Number if entries in the segment to be tessellated.

• nlevel (int) – Number of decomposition scales on the wavelet decomposition

• filter_length (int) – Size of the filter associated with the wavelet considered.

Returns

Maximum number of facets which can be considered.

Return type

int

src.sdwt2_sara(x_overlap, I, dims, offset, status, J, wavelet, Ncoefs)

Facet SARA operator.

Forward operator to compute the contribution of the SARA prior for a single input facet.

Parameters

• x_overlap (array[:, :]) – Image facet (with overlap).

• I (int[2]) – Starting index of the tile (without overlap) [1,2].

• dims (int[2]) – Dimensions of the image tile [1,2]

• offset (int[2]) – Offset to be considered for each dictionary w.r.t. the largest overlapping facet x_overlap (different overlap needed for each dictionary) [M,1].

• status (int[2]) – Indicates whether the facet is the first (or the last) along each dimension [1,2].

• J (int) – Number of decomposition levels considered.

• wavelet (cell{1, :} of string) – Name of the wavelet dictionaries considered {1,M}.

• Ncoefs (int[:]) – Number of wavelet coefficients for each scale, corresponding to each dictionary involved in the transform [M*(J+1),1].

Returns

SPsitLx – Wavelet coefficients.

Return type

array[:]

src.sdwt2_sara_faceting(x_overlap, I, offset, status, J, wavelet, Ncoefs)

Facet SARA operator (simplified version for faceting article).

Forward operator to compute the contribution of the SARA prior for a single input facet.

Parameters

• x_overlap (array[:, :]) – Image facet (with overlap).

• I (int[2]) – Starting index of the tile (without overlap) [1,2].

• offset (int[2]) – Offset to be considered for each dictionary w.r.t. the largest overlapping facet x_overlap (different overlap needed for each dictionary) [M,1].

• status (int[2]) – Indicates whether the facet is the first (or the last) along each dimension [1,2].

• J (int) – Number of decomposition levels considered.

• wavelet (cell{1, :} of string) – Name of the wavelet dictionaries considered {1,M}.

• Ncoefs (int[:]) – Number of wavelet coefficients for each scale, corresponding to each dictionary involved in the transform [M*(J+1),1].

Returns

SPsitLx – Wavelet coefficients.

Return type

array[:]

src.sdwt2_setup(N, I, dims, J, wavelet, L)

Setup faceted SARA prior.

Compute the auxliary variables (offset, overlap extension per dictionary) necessary to define the segmented wavelet transforms underlying the faceted SARA prior.

Parameters

• N (int[2]) – Full image dimension. [1,2]

• I (int[:, 2]) – Start index of each image tile (using 0-indexing) [Q,2]

• dims (int[:, 2]) – Dimensions of the image tiles. [Q,2]

• J (int) – Number of wavelet decomposition levels.

• wavelet (cell{:, 1} of string) – Name of the wavelet dictionaries. {M,1}

• L (int[:]) – Size of the wavelet filters. [M,1]

Returns

• I_overlap_ref (array) – start index of the facet within the full image. [Q,2]

• dims_overlap_ref (array) – Dimension of the facet (i.e., with overlap) to be extracted from the full image. [Q,2]

• I_overlap (array) – Start index of the facet (for each dictionary) within the full image. {Q,1}[M,2]

• dims_overlap (cell{:, 1} of array) – Dimension of the facet considered by each dictionary (including 0 coefficients from padding). {Q,1}[M,2]

• status (array) – Status of the facet along each dimension (i.e., whether it is the ‘first’ facet, ‘last’, ‘none’ of the previous option or ‘both’). The associated status value are respectively -1, 1, 0 and NaN. [Q,2]

• offset (array) – Offset to get the index of the first element (along each dimension) to be considered in the facet for each wavelet dictionary.

• pre_offset (array) – Number of coefficients to be cropped from the beginning of the global facet [M,2]. (offset to get position of the first non-zero element in the “global” facet)

• post_offset (array) – Number of coefficients to be cropped from the end of the global facet [M,2]. (offset to get position of the last non-zero element in the “global” facet)

• Ncoefs (cell) – Size of the details coefficients for each dictionary at each level of the decomposition {Q}[(M-1)*(J+1)+1,2] if Dirac dict. is present.

• pre_offset_dict (array) – For each dictionary, number of coefficients to be cropped from the beginning of the global facet [M,2].

• post_offset_dict (array) – For each dictionary, number of coefficients to be cropped from the end of the global facet [M,2].

Note

All indexes reported above (I_*) start from 0 (not from 1).

src.sdwt2_setup_test(N, I, dims, J, wavelet, L)

Setup faceted SARA prior.

Compute the auxliary variables (offset, overlap extension per dictionary) necessary to define the segmented wavelet transforms underlying the faceted SARA prior.

Parameters

• N (int[2]) – Full image dimension. [1,2]

• I (int[:, 2]) – Start index of each image tile (using 0-indexing) [Q,2]

• dims (int[:, 2]) – Dimensions of the image tiles. [Q,2]

• J (int) – Number of wavelet decomposition levels.

• wavelet (cell{:, 1} of string) – Name of the wavelet dictionaries. {M,1}

• L (int[:]) – Size of the wavelet filters. [M,1]

Returns

• I_overlap_ref (array) – start index of the facet within the full image. [Q,2]

• dims_overlap_ref (array) – Dimension of the facet (i.e., with overlap) to be extracted from the full image. [Q,2]

• I_overlap (array) – Start index of the facet (for each dictionary) within the full image. {Q,1}[M,2]

• dims_overlap (cell{:, 1} of array) – Dimension of the facet considered by each dictionary (including 0 coefficients from padding). {Q,1}[M,2]

• status (array) – Status of the facet along each dimension (i.e., whether it is the ‘first’ facet, ‘last’, ‘none’ of the previous option or ‘both’). The associated status value are respectively -1, 1, 0 and NaN. [Q,2]

• offset (array) – Offset to get the index of the first element (along each dimension) to be considered in the facet for each wavelet dictionary.

• pre_offset (array) – Number of coefficients to be cropped from the beginning of the global facet [M,2]. (offset to get position of the first non-zero element in the “global” facet)

• post_offset (array) – Number of coefficients to be cropped from the end of the global facet [M,2]. (offset to get position of the last non-zero element in the “global” facet)

• Ncoefs (cell) – Size of the details coefficients for each dictionary at each level of the decomposition {Q}[(M-1)*(J+1)+1,2] if Dirac dict. is present.

• pre_offset_dict (array) – For each dictionary, number of coefficients to be cropped from the beginning of the global facet [M,2].

• post_offset_dict (array) – For each dictionary, number of coefficients to be cropped from the end of the global facet [M,2].

src.sdwt2_test_nfacets(N, nfacets, nlevel, filter_length)

Test whether a number of facets is valid for the faceted wavelet transform is valid.

Test if a candiate number of facets is such that the overlap required by the faceted wavelet transform does not exceed the size of a tile (i.e., tessellation of 1:N into non-overlapping subsets of successive integers). If not, the function returns the maximum admissible number of facets satisfying this condition.

Parameters

• N (int) – Number if entries in the segment to be tessellated.

• nfacets (int) – Selected number of facets.

• nlevel (int) – Number of decomposition scales on the wavelet decomposition

• filter_length (int) – Size of the filter associated with the wavelet considered.

Returns

Number of facets which can be considered (equal to the initial value taken for nfacets if it satisfied the requirements).

Return type

int

src.split_range(nchunks, N, varargin)

Tessellates 1:N into multiple subsets.

Tessellates 1:N into (non-)overlapping subsets, each containing approximately the same number of indices, following the decomposition rules specified in varargin

Parameters

• nchunks (int) – Number of segments.

• N (int) – Number of indices.

• varargin (int) – Defines overlap between segments (if any)

Returns

rg – First/last index of each segment [nchunks, 2].

Return type

int[:, 2]

src.split_range_interleaved(nchunks, N)

Tessellates 1:N into interleaved subsets.

Tessellates 1:N into subsets of interleaved indices, each containing approximately the same number of indices (downsampling of 1:N).

Parameters

• nchunks (int) – Number of segments.

• N (int) – Total number of indices.

Returns

rg – First/last index of each segment {nchunks, 1}.

Return type

cell{:, 1} of array (int)