API

tiled_processing(tiled_view::TiledView, fct; verbose=true, dtype=eltype(tiled_view.parent), window_function=window_hanning)

Processes a raw dataset using tiled views by submitting each tile to the function fct and merging the results via the window_function.

Returns a TiledView of the result. The untiled result can be accessed via .parent member.

To be able to handle also functions that habe mutiple return values as a tuple, the accessor function can be used to extract the relevant value from the tuple. The default is the identity function, which is used for functions that return a single value. If a tuple of accessor functions is provided, each accessor function will be called and individual an return array for each element of the tuple is constructed and returned as a tuple.

Arguments

• tiled_view: the input data to decompose into a TiledView. No copies are made for the TiledView and the raw data can be accessed via .parent.
• fct: the function to be applied to each tile. The function should accept a single argument, which is the tile data.
• verbose: If true, diagnostic information on the window layout is printed.
• dtype: The element type of the new array. By default, it is the same as the type of the parent array of tiled_view.
• window_function: The window function as defined in IndexFunArrays to apply to the TiledView. The result is currently not any longer a view as it is unclear how to wrap the multiplication into a view. For this reason the TiledView without the window applied is also returned and can be used for assignments. By default a Hanning window (window_hanning) is used.
• accessor: A function to access the data in the tile. By default, it is the identity function.

tiled_processing(data, fct, tile_size, tile_overlap = tile_size .* 0; verbose=true, dtype=eltype(data), keep_center=false, window_function=nothing)

Processes a raw dataset using tiled views by wrapping the data in a TiledView, and submitting each tile to the function fct and merging the results via the window_function. Returns a TiledView of the result. The untiled result can be accessed via .parent member. Note that this version with the tile_size adds a view conveniences: If the tile size specifies fewer dimensions than the data, the trailing dimensions are automatically expanded to match the full size of the data. The default nothing in the windowfunction assures that no window is applied if no overlap is used. With overlap this changes automatically to a Hanning window. Furthermore, as opposed to the other version, the keepcenter option has the default value of false, which is more convenient for most applications that just tile arrays in a matching way.

If the first processed tile returns an array with a size that is neither equal to the input tile size or a projection thereof, the result is a tuple of arrays of the same size as the input tile size, an array of arrays one for each tile is returned.

Arguments

• data: the input data to decompose into a TiledView. No copies are made for the TiledView and the raw data can be accessed via .parent.
• fct: the function to be applied to each tile. The function should accept a single argument, which is the tile data.
• tile_size: A Tuple describing the size of each tile. This size will form the first N dimensions of the result of size(myview). The second N dimensions refer to N-dimensional tile numbering.
• tile_overlap: Tuple specifying the overlap between successive tiles in voxels. This implicitely defines the pitch between tiles as (tile_size .- tile_overlap).
• verbose: If true, diagnostic information on the window layout is printed.
• dtype: The element type of the new array. By default, it is the same as the type of the parent array of data.
• keep_center: This boolean (default: false) specifies whether the center of the parent data will be aligned with the center of the central tile. If false, the first tile starts at offset zero.
• window_function: The window function as defined in IndexFunArrays to apply to the TiledView. The result is currently not any longer a view as it is unclear how to wrap the multiplication into a view. For this reason the TiledView without the window applied is also returned and can be used for assignments. By default a Hanning window (window_hanning) is used.

Example

julia> res = tiled_processing(ones(10,10), (a)->10*a, (2,2), (0,0), verbose=false).parent
10×10 Matrix{Float64}:
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0
 10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0  10.0

julia> tiled_processing(ones(10,20), (a)->sum(a, dims=2), (2,), verbose=false).parent
10×1 Matrix{Float64}:
 20.0
 20.0
 20.0
 20.0
 20.0
 20.0
 20.0
 20.0
 20.0
 20.0

julia> fct = (a)->[3 .*a, sum(a, dims=2), "result: $(sum(a))"]; # a function that returns a tuple of three values of very different types

julia> tiled_processing(ones(5,6), fct, (2,), verbose=false)
3-element Vector{AbstractArray}:
 [3.0 3.0 … 3.0 3.0; 3.0 3.0 … 3.0 3.0;;; 3.0 3.0 … 3.0 3.0; 3.0 3.0 … 3.0 3.0;;; 3.0 3.0 … 3.0 3.0; 0.0 0.0 … 0.0 0.0;;;;]
 [6.0; 6.0;;; 6.0; 6.0;;; 6.0; 0.0;;;;]
 ["result: 12.0"; "result: 12.0"; "result: 6.0";;]

TiledView(data::F, tile_size::NTuple{N,Int}, 
          tile_overlap::NTuple{N,Int} = tile_size .* 0, 
          tile_center::NTuple{M,Int} = (mod.(tile_size,2) .+ 1)
          ; pad_value::T, keep_center=true)

Creates an 2N dimensional view of the data by tiling the N-dimensional data as specified by tilesize, tileoverlap and optionally tile_center.

Arguments

• data: the input data to decompose into a TiledView. No copies are made for the TiledView and the raw data can be accessed via .parent.
• tile_size: A Tuple describing the size of each tile. This size will form the first N dimensions of the result of size(myview). The second N dimensions refer to N-dimensional tile numbering.
• tile_overlap: Tuple specifying the overlap between successive tiles in voxels. This implicitely defines the pitch between tiles as (tile_size .- tile_overlap).

Keyword Argument

• pad_value: Specifies the answer that is returned when get_index is applied to a position outside the source array.
• keep_center: This boolean specifies whether the center of the parent data will be aligned with the center of the central tile. If false, the first tile starts at offset zero.
• tile_center: Only used if keep_center is true. It defines the center position in the central tile. The default is tile_size .÷ 2 .+1.

Examples

julia> a = TiledView(reshape(1:49,(7,7)), (4, 4),(1, 1));

julia> a.parent
7×7 reshape(::UnitRange{Int64}, 7, 7) with eltype Int64:
 1   8  15  22  29  36  43
 2   9  16  23  30  37  44
 3  10  17  24  31  38  45
 4  11  18  25  32  39  46
 5  12  19  26  33  40  47
 6  13  20  27  34  41  48
 7  14  21  28  35  42  49

julia> size(a)
(4, 4, 3, 3)

function TiledWindowView(data::AbstractArray{T,M}, tile_size::NTuple{M,Int};
                         rel_overlap::NTuple{M,Float64}=tile_size .*0 .+ 1.0,
                         window_function=window_hanning, get_norm=false, verbose=false, offset=CtrFT) where {T, M}

Creates an 2N dimensional view of the data by tiling the N-dimensional data as specified by tilesize, tileoverlap and optionally tilecenter. Additionally a window is applied to this view. If the windowtype as defined in IndexFunArrays sums up to one, which is the case for windowlinear and windowhanning, a linear decomposition of the data is obtained apart from possible border effects. data. the inputdata to decompose into a TiledView. No copies are made for the TiledView and the raw data can be accessed via myview.parent.

tile_size. A Tuple describing the size of each tile. This size will form the first N dimensions of the result of size(myview). The second N dimensions refer to N-dimensional tile numbering.

rel_overlap. Tuple specifying the relative overlap between successive tiles. The absolute overlap is then calculated as round.(Int,tile_size./2.0 .* rel_overlap).

window_function. The window function as defined in IndexFunArrays to apply to the TiledView. The result is currently not any longer a view as it is unclear how to wrap the multiplication into a view. For this reason the TiledView without the window applied is also returned and can be used for assignments. By default a von Hann window (window_hanning) is used.

get_norm. An optional Boolean argument allowing to also obtain the normalization map for the boarder pixels, which not necessarily undergo all required window operations. In a future version it may be possible to automatically lay out the windowing such that this effect can be avoided.

verbose. If true, diagnostic information on the window layout is printed.

offset. defines where the center of the window is placed. See IndexFunArrays.jl for details.

Returns

myview, matchingwindow = TiledWindowView ... a Tuple of two or three (getnorm=true) with

myview. the TiledView of the data without the window which can also be written to.

matching_window. a window that can be applied to the view via multiplication myview.*matching_window This is intentionally not provided as a product to separate the features conceptually when it comes to write access.

normalized. only returned for get_norm=true. Contains an array with the normalization information by mapping the window back to the original data. This is useful for incomplete coverage of the tiles as well as using windows which do not sum up to one in the tiling process.

Note that it may be dangerous to directly access the view via a simple .+= operation as it is not entirely clear, whether it is always garanteed that there could not be any running conditions with read-write operations, since some points in the referenced array are accessed multiple times. To avoid such an effect, you can, for example, only acess every second tile along each dimension in one call.

Examples

julia> data = ones(10,10).+0.0;

julia> myview, matching_window = TiledWindowView(data, (5, 5); verbose=true);
[ Info: Tiles with pitch (3, 3) overlap by (2, 2) pixels.
[ Info: Window starts at (0.5, 0.5) and ends at (2.5, 2.5).

julia> size(myview)
(5, 5, 5, 5)

julia> matching_window
5×5 IndexFunArrays.IndexFunArray{Float64, 2, IndexFunArrays.var"#360#362"{Float64, Tuple{Int64, Int64}, Tuple{Int64, Int64}, Tuple{Float64, Float64}, Tuple{Float64, Float64}}}:
 0.0214466  0.125     0.146447  0.125     0.0214466
 0.125      0.728553  0.853553  0.728553  0.125
 0.146447   0.853553  1.0       0.853553  0.146447
 0.125      0.728553  0.853553  0.728553  0.125
 0.0214466  0.125     0.146447  0.125     0.0214466

julia> windowed = collect(myview .* matching_window);

julia> myview[:,:,:,:].=0;  # cleares the original array

julia> myview.parent
10×10 Matrix{Float64}:
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0

julia> myview .+= windowed;  # writes the windowed data back into the array

julia> data # lets see if the weigths correctly sum to one?
10×10 Matrix{Float64}:
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0
 1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0

julia> # This result may also be used for subsequent normalization but can also be directly obtained by
 
julia> myview, matching_window, normalized = TiledWindowView(rand(10,10).+0, (5, 5); get_norm=true);

get_window(A::TiledView; window_function=window_hanning, get_norm=false, verbose=false, offset = CtrFT);

Calculates a window matching to the TiledView.

window_function. The window function as defined in IndexFunArrays to apply to the TiledView. The result is currently not any longer a view as it is unclear how to wrap the multiplication into a view. For this reason the TiledView without the window applied is also returned and can be used for assignments. By default a von Hann window (window_hanning) is used. For even sizes the window is centered at the integer coordinate right of the middle position (CtrFT).

get_norm. An optional Boolean argument allowing to also obtain the normalization map for the boarder pixels, which not necessarily undergo all required window operations. In a future version it may be possible to automatically lay out the windowing such that this effect can be avoided.

verbose. If true, diagnostic information on the window layout is printed.

offset. defines where the center of the window is placed. See IndexFunArrays.jl for details.

Returns

matching_window. a window that can be applied to the view via multiplication myview.*matching_window This is intentionally not provided as a product to separate the features conceptually when it comes to write access.

normalized. only returned for get_norm=true. Contains an array with the normalization information by mapping the window back to the original data. This is useful for incomplete coverage of the tiles as well as using windows which do not sum up to one in the tiling process.

Examples

julia> data = ones(10,10).+0.0;

julia> myview = TiledView(data, (5, 5), (2,2));

julia> win = get_window(myview, verbose=true);
[ Info: Tiles with pitch (3, 3) overlap by (2, 2) pixels.
[ Info: Window starts at (0.5, 0.5) and ends at (2.5, 2.5).

julia> win
5×5 IndexFunArrays.IndexFunArray{Float64, 2, IndexFunArrays.var"#360#362"{Float64, Tuple{Int64, Int64}, Tuple{Int64, Int64}, Tuple{Float64, Float64}, Tuple{Float64, Float64}}}:
 0.0214466  0.125     0.146447  0.125     0.0214466
 0.125      0.728553  0.853553  0.728553  0.125
 0.146447   0.853553  1.0       0.853553  0.146447
 0.125      0.728553  0.853553  0.728553  0.125
 0.0214466  0.125     0.146447  0.125     0.0214466

see TiledWindowView() for more examples.

Base.size(A::TiledView)

Returns the size of the TiledView. See TiledView for how the size is determined.

get_num_tiles(data::TiledView)

Returns the number of tiles

tile_centers(A, scale=nothing)

Returns the relative center coordinates of integer tile centers with respect to the integer center 1 .+ size(A) .÷ 2 The tuple scale is used to multiply the relative position with a physical pixelsize. See also: eachtilerelpos for a corresponding iterator

eachtile(tiled_view::TiledView)

Returns an iterator which iterates through all tiles. Depending on your application you may also want to use tiled_processing for a convenient way to apply a function to each tile and join all tiles back together. If you need simultaneous access to the tiles and tile numbers, you can also use eachtilenumber.

eachtilenumber(tiled_view::TiledView)

Returns an iterator iterating though all the tile numbers. If you need access to the tiles themselves, use eachtile

eachtilerelpos(A, scale=nothing)

Returns a generator that iterates through the relative distance of each tile center 1 .+ size(A).÷2 to the center of the the untiled parent array 1 .+ size(parent).÷2 The tuple scale is used to multiply the relative position with a physical pixelsize.

get_result_size(tiled_view::TiledView, res_tile::AbstractArray, arr)

returns a tuple of the size of the whole results arrey, considering the tiled_view of the input data and the size of a single result tile res_tile obtained by processing the first tile of th input data.

compatible_sizes(tiled_view, res_tile)

determinse whether a tiled_view is compatible with a processed result array of a tile res_tile.

alloc_zeros(tiled_view::TiledView, res_tile::AbstractArray, dtype=nothing)

a helper function to allocate a new array of zeros with the same size as the tile res_tile. The function is used in the tiled_processing function to allocate the result array. It dispatches for a tuple input type to allocate separately for each of the return types as stored in res_tile. Allocation is only done for AbstractArrays, whereas other types are just kept in the tile-wise way as an Array of results of type Any.

add_to_member!(res::Vector, res_tile::Union{Tuple, Vector}, wins::Vector, n)

adds a plain array res_tile to a result Vectorres at position n. res is allocated to hold several results (such as TiledViews) as specified by the first call to the function when using the tiled_processing function.

add_to_member!(res::Vector, res_tile::Union{Tuple, Vector}, wins::Vector, n)

adds a plain array res_tile to a TiledView result array res at position n.

add_to_member!(res, res_tile, win, n)

add any type of result to a result array res at position n of type any just storing the corresponding results of individual calls. Note that a windoe win is ignored here.

zeros_like(A::TiledView, ::Type{T}=eltype(A.parent))

returns a new TiledView of the same size as A filled with zeros.

Arguments:

• A: the TiledView to be used as a template for the new array.
• T: the element type of the new array. By default, it is the same as the type of the parent array of A.

zeros_like(A::TiledView, reduced_size::NTuple, ::Type{T}=eltype(A.parent)) where {T}

returns a new TiledView of referring to a zero-array of size reduced_size but with the same tile-layout as A.

Arguments:

• A: the TiledView to be used as a template for the new array.
• reduced_size: the size of the new array. The first N dimensions are the tile size, the second N dimensions are the number of tiles.
• T: the element type of the new array. By default, it is the same as the type of the parent array of A.

ones_like(A::TiledView, ::Type{T}=eltype(A.parent))

returns a new TiledView of the same size as A filled with ones.

Arguments:

• A: the TiledView to be used as a template for the new array.
• T: the element type of the new array. By default, it is the same as the type of the parent array of A.