Reference

resize!(grid::SpmGrid, args...; kwargs...)

Resizes the grid in its dimensions. Arguments and keyword-arguments are similar as for the ImageTransformations.imresize function.

Examples:

julia> resize!(grid, ratio=0.5)  # resize all dimensions by a factor 0.5
julia> resize!(grid, ratio=(0.5, 0.5))  # resize x and y dimensions by a factor 0.5
julia> resize!(grid, ratio=(0.5, 0.5, 2.0))  # resize x and y dimensions by a factor 0.5, z dimension by a factor of 2
julia> resize!(grid, 64, 64)    # resize x and y dimensions to a specific pixelsize
julia> resize!(grid, 32, 96, 128)   # resize all dimensions to a specific pixelsize

add_channel!(func::Function, grid::SpmGrid, name::AbstractString, unit::AbstractString,
    args...; skip_bwd::Bool=false, force::Bool=false)::Nothing

Adds a generated channel with name, unit and data to the grid. The channel is generated by the function func that takes other channels/parameters specified by args... as input parameters. Any broadcasting functionality should be implemented in func. The name cannot be the same as names in the original channel names. If the name exists in the generated channel names, it will be overwritten. If skip_bwd is false (default), then bwd channels will be added if feasible. If force is true, then the consistency checks for name and dimensions are overriden.

Examples

julia> grid = load_grid("file.3ds")
julia> add_channel!(x -> abs(x), grid, "CurrentAbs", "A", "Current")
julia> add_channel!((x,y) -> x + y, grid, "", "A", "Current", "AbsCurrent")

add_channel!(grid::SpmGrid, name::AbstractString, unit::AbstractString,
    data::AbstractArray{Float64}; force::Bool=false)::Nothing::Nothing

Adds a generated channel with name, unit and data to the grid. The data must be of the same size as channel data in the grid, i.e. grid.points x grid.pixelsize.... The name cannot be the same as names in the original channel names. If the name exists in the generated channel names, it will be overwritten. If force is true, then the consistency checks for name and dimensions are overriden.

add_parameter!(func::Function, grid::SpmGrid, name::AbstractString, unit::AbstractString,
    args...::AbstractString; force::Bool=false)::Nothing

Adds a generated parameter with name, unit and data to the grid. The parameter is generated by the function func that takes other parameter/channels specified by args... as input parameters. Any broadcasting functionality should be implemented in func. The name cannot be the same as names in the original parameter names. If the name exists in the generated parameter names, it will be overwritten. If force is true, then the consistency checks for name and dimensions are overriden.

Examples

julia> grid = load_grid("file.3ds")
julia> add_parameter!(x -> abs(x), grid, "Scan:ExcitationAbs", "V", "Scan:Excitation")

add_parameter!(grid::SpmGrid, name::AbstractString, unit::AbstractString,
    data::AbstractArray{Float64}; force::Bool=false)::Nothing

Adds a generated parameter with name, unit and data to the grid. The data must be of the same size as parameter data in the grid, i.e. grid.pixelsize. The name cannot be the same as names in the original parameter names. If the name exists in the generated parameter names, it will be overwritten. If force is true, then the consistency checks for name and dimensions are overriden.

channel_names(grid::SpmGrid, skip_bwd=true)::Array{String}

Returns all channel names in grid. If skip_bwd is true, then the channel names for the bwds direction are not returned.

deconvolve_force!(grid::SpmGrid, response_channel::String,
    f₀::Float64=0., A::Float64=0., k::Float64=1800.;
    sweep_channel::String="", bwd::Bool=true)::Nothing

Applies the Sadar Jarvis force deconvolution algorithm as implemented in the SpmSpectroscopy package to each point in the grid. response_channel should refer to the "Frequency Shift" channel and sweep_channel (which defaults to the sweep signal of the grid) should be tip height "Z".

In addition, the along the experimental parameters f₀ (resonance frequency), A (oscillation amplitude), and k (cantilever stiffness) can be specified. For k the default values is 1800 N/m, which is a typical value for qPlus sensors. If the values for f₀ and A are left at their default values of 0., the values will be extracted from the header data.

Adds the channels "Force z" and "Potential" to the SpmGrid grid. Additionally, the channels "Force x" and "Force y" will be calculated by differentiation of the Potential in x and y direction, respectively. The x and y force components will not be calculated if the sweep_channel is not sorted.

If bwd is true (default), the plot will include data from backward sweep as well (if they exist).

fit_KPFM!(grid::SpmGrid, response_channel::String;
    sweep_channel::String="", bwd::Bool=true)::Nothing

Fits KPFM data. This is done by fitting a parabola to the graoh of response_channel vs sweep_channel on the grid. If not explicitely specified, sweep_channel defaults to the sweep signal of the grid.

For KPFM, the response channel should be the "Frequency Shift" channel and the sweep channel is the "Bias".

Adds the parameters "KPFM:Bias", "KPFM:Frequency Shift", "KPFM:Residuals AbsSum" and the channels "KPFM:Fit", "KPFM:Residuals" to the SpmGrid grid.

If bwd is true (default), the plot will include data from backward sweep as well (if they exist).

get_channel(grid::SpmGrid, name::AbstractString,
    x_index::GridRange=:, y_index::GridRange=:, channel_index::GridRange=:;
    bwd::Bool=false)::SubArray{Float64}

Returns the data for the channel name at the point(s) specified by x_index, y_index The channel data can be indexed by channel_index. If bwd is true, the bwd channel is returned if it exists. If view is true (default), then a view(@ref Base.view) is returned , otherwise a copy.

get_channel_unit(grid::SpmGrid, name::AbstractString)::AbstractString

Returns the unit associated with the channel name.

get_data(grid::SpmGrid, name::AbstractString,
    x_index::GridRange=:, y_index::GridRange=:, channel_index::GridRange=:;
    bwd::Bool=false)::SubArray{Float64}

Returns the data for the channel or parameter name at the point(s) specified by x_index, y_index Channel data can also be indexed by channel_index. If bwd is true, the bwd channel is returned if it exists. If view is true (default), then a view(@ref Base.view) is returned , otherwise a copy.

get_parameter(grid::SpmGrid, name::AbstractString,
    x_index::GridRange=:, y_index::GridRange=:; view::Bool=true)::Union{Array{Float64},SubArray{Float64}}

Returns the value for parameter name at the point(s)specified by x_index, y_index. If view is true (default), then a view(@ref Base.view) is returned , otherwise a copy.

get_parameter_unit(grid::SpmGrid, name::AbstractString)::AbstractString

Returns the unit associated with the parameter name.

has_channel(grid::SpmGrid, name::AbstractString; bwd::Bool=false)::Bool

Returns true if channel name is present in the grid. If bwd is true, the checks for the existance of the bwd channel.

has_parameter(grid::SpmGrid, name::AbstractString)::Bool

Returns true if parameter name is present in the grid.

interactive_display(fname::String, response_channel::String="", response_channel2::String="", parameter::String="";
    bwd::Bool=false, fig::Any=nothing, backend::Module=Main, kwargs...)::Any

Display the grid in an interactive GUI that can be used in Pluto, Jupyter, or other interactive environments. response_channel specifies the initial choice of the response channel, response_channel2 specifies the initial choice of the response channel for the second line plot, parameter specifies the initial parameter to plot.

Before using this function, a Makie backend (GLMakie, CairoMakie or WGLMakie) should be imported and the figure can be set up and passed via the fig keyword argument.

interactive_display(grid::SpmGrid, response_channel::String="", response_channel2::String="", parameter::String="";
    bwd::Bool=false, fig::Any=nothing, backend::Module=Main)::Any

Display the grid in an interactive GUI that can be used in Pluto, Jupyter, or other interactive environments. response_channel specifies the initial choice of the response channel, response_channel2 specifies the initial choice of the response channel for the second line plot, parameter specifies the initial parameter to plot.

Before using this function, a Makie backend (GLMakie, CairoMakie or WGLMakie) should be imported and the figure can be set up and passed via the fig keyword argument.

load_grid(images::Vector{<:SpmImage}, by::Function=im -> im.z
name::AbstractString="Z", unit::AbstractString="m";
only_overlap::Bool=false, header_only::Bool=false)::SpmGrid

Loads a grid from a stack of images. The sweep signal is specified with the by argument, as well as name and unit. The first image determines the pixel density, as well as the channels that will be available. Here, the backward channels will be associated with the backward scan direciton in the images. Ideally, all images should have the same pixel density and recorded channels. if only_overlap is true, then data is returned only for the pixels that are overlapping in all images. If header_only is true, then only the header is created.

load_grid(filenames::Vector{<:AbstractString}, by::Function=im->im.z,
    name::AbstractString="Z_", unit::AbstractString="m";
    only_overlap::Bool=false, header_only::Bool=false)::SpmGrid

Loads a grid from a stack of image files. The sweep signal is specified with the by argument, as well as name and unit. The first image determines the pixel density, as well as the channels that will be available. Here, the backward channels will be associated with the backward scan direciton in the images. Ideally, all images should have the same pixel density and recorded channels. if only_overlap is true, then data is returned only for the pixels that are overlapping in all images. If header_only is true, then only the header is created.

load_grid(filename::AbstractString; header_only::Bool=false)

Loads a grid from a binary file. If header_only is true, then only the header is loaded.

parameter_names(grid::SpmGrid)::Array{String}

Returns all parameter names in grid.

plot_cube(grid::SpmGrid, response_channel::String,
    x_index::GridRange=:, y_index::GridRange=:, channel_index::GridRange=:;
    bwd::Bool=false, ax::Any=nothing, backend::Module=Main,
    kwargs...)::NamedTuple

Plots a cube of response_channel in the three-dimensional data spanned by the x,y plane and the sweep signal. Indexing is done through x_index, y_index and channel_index and should be done such that a three-dimensional array is obtained. If bwd is set to true, then data from the backward sweep is plotted if it exists.

Before using this function, a Makie backend (GLMakie, CairoMakie or WGLMakie) should be imported and the figure or axis should be set up. A particular Axis can be specified via the ax keyword argument. By default, the Makie backend from the Main module is used; it can also be directly specified via the backend keyword argument.

Extra keyword arguments can be specified and will be passed through to the plot function.

Returns a NamedTuple containing the volume-plot, and a colorbar label.

plot_cube(data::NamedTuple, ax::Any, ax_cb::Any, backend::Module; kwargs...)::Nothing

Plots a cube from the NamedTuple data on Axis ax. A colorbar is also plotted on ax_cb. A Makie backend should be given and extra keyword arguments can be provided.

plot_line(grid::SpmGrid, response_channel::String,
    x_index::GridRange, y_index::GridRange, channel_index::GridRange=nothing;
    sweep_channel::String="", bwd::Bool=true, ax::Any=nothing, backend::Module=Main,
    kwargs...)::NamedTuple

Plots the response_channel along a line in the three-dimensional data spanned by x,y plane and the spectroscopy data. Indexing is done through x_index, y_index and channel_index and should be done such that a one-dimensional array is obtained. It is also possible to plot response_channel vs sweep_channel (which defaults to the sweep signal if not specified) for one point in the grid If bwd is true (default), the plot will include data from backward sweep as well (if they exist).

Before using this function, a Makie backend (GLMakie, CairoMakie or WGLMakie) should be imported and the figure or axis should be set up. A particular Axis can be specified via the ax keyword argument. By default, the Makie backend from the Main module is used; it can also be directly specified via the backend keyword argument.

Extra keyword arguments can be specified and will be passed through to the plot function. Keyword arrguments with the suffix _bwd will be used for plotting of the backward scan.

Returns a NamedTuple.

plot_line(data::NamedTuple, ax::Any, backend::Module; bwd::Bool=true, kwargs...)::Nothing

Plots a line from the NamedTuple x vs y and x_bwd vs y_bwd on Axis ax

plotparameterplane(grid::SpmGrid, parameter::String, xindex::GridRange=:, yindex::GridRange=:; ax::Any=nothing, backend::Module=Main, kwargs...)::NamedTuple

Plots values of parameters as a function of the x,y plane Indexing is done through x_index, y_index.

Before using this function, a Makie backend (GLMakie, CairoMakie or WGLMakie) should be imported and the figure or axis should be set up. A particular Axis can be specified via the ax keyword argument. By default, the Makie backend from the Main module is used; it can also be directly specified via the backend keyword argument.

Extra keyword arguments can be specified and will be passed through to the plot function.

Returns a NamedTuple containing the heatmap, the colorbar label and the plot label.

plot_plane(grid::SpmGrid, response_channel::String,
    x_index::GridRange, y_index::GridRange, channel_index::GridRange=:;
    bwd::Bool=false, ax::Any=nothing, backend::Module=Main,
    kwargs...)::NamedTuple

Plots a plane of response_channel in the three-dimensional data spanned by x,y plane and the sweep signal. Indexing is done through x_index, y_index and channel_index and should be done such that a two-dimensional array is obtained. If bwd is set to true, then data from the backward sweep is plotted if it exists.

Before using this function, a Makie backend (GLMakie, CairoMakie or WGLMakie) should be imported and the figure or axis should be set up. A particular Axis can be specified via the ax keyword argument. By default, the Makie backend from the Main module is used; it can also be directly specified via the backend keyword argument.

Extra keyword arguments can be specified and will be passed through to the plot function.

Returns a NamedTuple containing the heatmap, the colorbar label and the plot label.

plot_plane(data::NamedTuple, ax::Any, ax_cb::Any, backend::Module; kwargs...)::Nothing

Plots a plane from the NamedTuple data on Axis ax. A colorbar is also plotted on ax_cb. A Makie backend should be given and extra keyword arguments can be provided.

plot_spectrum(grid::SpmGrid, sweep_channel::String, response_channel::String,
    x_index::GridRange, y_index::GridRange, channel_index::GridRange=:;
    bwd::Bool=true, ax::Any=nothing, backend::Module=Main,
    kwargs...)::NamedTuple

Plots a line plot of response_channel vs sweep_channel on the given x_index and y_index. If sweep_channel is "", then the sweep signal will be used for sweep_channel. Additionally, the spectrum data can be indexed by channel_index. If bwd is true (default), the plot will include data from backward sweep as well (if they exist).

Before using this function, a Makie backend (GLMakie, CairoMakie or WGLMakie) should be imported and the figure or axis should be set up. A particular Axis can be specified via the ax keyword argument. By default, the Makie backend from the Main module is used; it can also be directly specified via the backend keyword argument.

Extra keyword arguments can be specified and will be passed through to the plot function. Keyword arrguments with the suffix _bwd will be used for plotting of the backward scan.

Returns a NamedTuple.

point_to_xyindex(grid::SpmGrid, point::Vector{Float64})::Tuple{Int,Int}

Converts point (in physical units) of grid to indexx and indexy

xyindex_to_point(grid::SpmGrid, index_x::Int, index_y)::Tuple{Float64,Float64}

Converts index_x and index_y of grid to point coordinates in physical units.