CoordinateSystems.jl Documentation

mutable struct CartesianCoordinates{T <: Real, dim} <: Coordinates{T, dim}

A mutable struct representing Cartesian coordinates in a dim-dimensional space, where T is the type of the coordinate values (typically Float64, Int or BigFloat).

CircleCoordinates{T} <: GeneralSphericalCoordinates{T, Val{1}, Nothing, 2}

Type for circular coordinates in 2D space, where T is the type of the coordinate values (typically Float64, Int or BigFloat). The coordinates are represented as (azi), with polar set to nothing and r fixed to 1.

abstract type Coordinates{T <: Real, dim} end

An abstract type representing a coordinate system in a dim-dimensional space, where T is the type of the coordinate values (typically Float64, Int or BigFloat).

mutable struct GeneralSphericalCoordinates{T <: Real, Tr <: Union{Val{1}, T}, Tp <: Union{Nothing, T}, dim} <: Coordinates{T, dim}

A mutable struct representing spherical coordinates in a dim-dimensional space, where T is the type of the coordinate values (typically Float64, Int or BigFloat), Tr is the type of the radial coordinate (can be fixed to 1 for unit sphere), Tp is the type of the polar coordinate (can be nothing for 2D polar coordinates), and dim is the dimension of the coordinate system.

PlanarCoordinates{T} <: CartesianCoordinates{T, 2}

Type for 2D Cartesian coordinates, where T is the type of the coordinate values (typically Float64, Int or BigFloat).

PolarCoordinates{T} <: GeneralSphericalCoordinates{T, T, Nothing, 2}

Type for polar coordinates in 2D space, where T is the type of the coordinate values (typically Float64, Int or BigFloat). The coordinates are represented as (r, azi), with polar set to nothing.

SpatialCoordinates{T} <: CartesianCoordinates{T, 3}

Type for 3D Cartesian coordinates, where T is the type of the coordinate values (typically Float64, Int or BigFloat).

SphereCoordinates{T} <: GeneralSphericalCoordinates{T, Val{1}, T, 3}

Type for spherical coordinates on the unit sphere in 3D space, where T is the type of the coordinate values (typically Float64, Int or BigFloat). The coordinates are represented as (polar, azi), with r fixed to 1.

SphericalCoordinates{T} <: GeneralSphericalCoordinates{T, T, T, 3}

Type for full spherical coordinates in 3D space, where T is the type of the coordinate values (typically Float64, Int or BigFloat). The coordinates are represented as (r, polar, azi).

function Base.convert(::Type{PolarCoordinates}, c::CircleCoordinates)

Converts a CircleCoordinates to PolarCoordinates. The radius is set to 1.

function Base.convert(::Type{SphericalCoordinates}, s::SphereCoordinates)

Converts a SphereCoordinates to SphericalCoordinates. The radius is set to 1.

function Base.convert(::Type{T1}, g::T2; truncate::Bool=false) where {T1 <: Union{PolarCoordinates, CircleCoordinates}, T2 <: Union{SphericalCoordinates, SphereCoordinates}}

Converts SphericalCoordinates or SphereCoordinates to PolarCoordinates or CircleCoordinates.

function Base.convert(::Type{T1}, g::T2; truncate::Bool=false) where {T1 <: Union{SphericalCoordinates, SphereCoordinates}, T2 <: Union{PolarCoordinates, CircleCoordinates}}

Converts PolarCoordinates or CircleCoordinates to SphericalCoordinates or SphereCoordinates.

function Base.convert(::Type{CircleCoordinates}, p::PolarCoordinates{T}; truncate::Bool=false) where {T <: Real}

Converts a PolarCoordinates{T} to CircleCoordinates{T}. If the radius p.r is approximately 1 or truncate is set to true, the conversion projects the coordinates onto the unit circle. Otherwise, an error is raised.

function Base.convert(::Type{SphereCoordinates}, b::SphericalCoordinates{T}; truncate::Bool=false) where {T <: Real}

Converts a SphericalCoordinates{T} to SphereCoordinates{T}. If the radius b.r is approximately 1 or truncate is set to true, the conversion projects the coordinates onto the unit sphere. Otherwise, an error is raised.

function Base.convert(::Type{T}, x::CartesianCoordinates; truncate::Bool=false) where {T <: Union{CircleCoordinates, PolarCoordinates}}

Converts a CartesianCoordinates with dimension 2 to either CircleCoordinates or PolarCoordinates. If truncate is set to true, the conversion projects the coordinates onto the unit circle or unit polar coordinates, respectively. If truncate is false, the conversion requires the Cartesian coordinates to have a norm close to 1.

function Base.convert(::Type{T}, x::CartesianCoordinates; truncate::Bool=false) where {T <: Union{SphereCoordinates, SphericalCoordinates}}

Converts a CartesianCoordinates with dimension 3 to either SphereCoordinates or SphericalCoordinates. If truncate is set to true, the conversion projects the coordinates onto the unit sphere or spherical coordinates, respectively. If truncate is false, the conversion requires the Cartesian coordinates to have a norm close to 1.

function Base.convert(::Type{T}, g::GeneralSphericalCoordinates) where {T <: CartesianCoordinates}

Converts a GeneralSphericalCoordinates to a CartesianCoordinates{T, dim} where dim is either 2 or 3. The conversion uses the spherical coordinates to compute the Cartesian coordinates.

function Base.convert(::Type{Vector}, x::CartesianCoordinates{T, dim}) where {T <: Real, dim}

Converts a CartesianCoordinates{T, dim} to a Vector{T} by extracting the coordinate values.

function Base.convert(::Type{CartesianCoordinates{T1, dim1}}, x::CartesianCoordinates{T, dim}) where {T1 <: Real, dim1, T <: Real, dim}

Converts a CartesianCoordinates{T, dim} to CartesianCoordinates{T1, dim1} by resizing the vector and converting the elements to type T1. If dim1 is greater than dim, the additional elements are set to zero.

function Base.getindex(x::CartesianCoordinates{T, dim}, keys::Union{Int, Symbol, AbstractVector{Int}})  where {T <: Real, dim}

Returns the value of the coordinate or property specified by keys from the CartesianCoordinates{T, dim} instance x. The keys can be an integer index, a symbol representing a property, or an array of indices.

function Base.getproperty(s::GeneralSphericalCoordinates{T, Tr, Tp, dim}, i::Symbol) where {T, Tr, Tp, dim}

Returns the value of the property i from the GeneralSphericalCoordinates{T, Tr, Tp, dim} instance s. The properties include :r, :polar (or :θ, :theta), and :azi (or :φ, :phi, :azimuth). The dimension is also included as :dim. If an invalid property is specified, an error is raised.

function Base.getproperty(x::CartesianCoordinates{T, dim}, i::Symbol) where {T <: Real, dim}

Returns the value of the property i from the CartesianCoordinates{T, dim} instance x. The properties include :dim, :xs, and coordinate values like :x, :y, :z, or :xN for dimensions greater than 3.

function Base.iterate(s::GeneralSphericalCoordinates{T, Tr, Tp, dim}, state::Int64=1) where {T, Tr, Tp, dim}

Iterates over the properties of a GeneralSphericalCoordinates{T, Tr, Tp, dim} instance s. Order: r, polar, azi.

function Base.length(x::Coordinates{T, dim}) where {T <: Real, dim}

Returns the dimension of the coordinate system represented by x, which is an instance of Coordinates{T, dim}.

function Base.propertynames(x::CartesianCoordinates{T, dim}) where {T <: Real, dim}

Returns a tuple of property names for the CartesianCoordinates{T, dim} instance x. The properties include :xs, :dim, and coordinate values like :x, :y, :z, or :xN for dimensions greater than 3.

function Base.propertynames(s::GeneralSphericalCoordinates{T, Tr, Tp, dim}) where {T, Tr, Tp, dim}

Returns a tuple of property names for the GeneralSphericalCoordinates{T, Tr, Tp, dim} instance s. The properties include :r, :polar (or :θ, :theta), and :azi (or :φ, :phi, :azimuth). The dimension is also included as :dim.

function Base.resize!(x::CartesianCoordinates{T, dim}, new_dim::Int) where {T <: Real, dim}

Resizes the CartesianCoordinates{T, dim} instance x to a new dimension new_dim. If new_dim is greater than the current dimension, the additional elements are set to zero. If new_dim is less than the current dimension, the excess elements are removed.

function Base.setindex!(x::CartesianCoordinates{T, dim}, val, keys::Union{Int, Symbol, AbstractVector{Int}}) where {T <: Real, dim}

Sets the value of the coordinate or property specified by keys in the CartesianCoordinates{T, dim} instance x to val. The keys can be an integer index, a symbol representing a property, or an array of indices. If an invalid property is specified, an error is raised.

function Base.setproperty!(s::GeneralSphericalCoordinates{T, Tr, Tp, dim}, i::Symbol, val) where {T, Tr, Tp, dim}

Sets the property i of the GeneralSphericalCoordinates{T, Tr, Tp, dim} instance s to the value val. The properties include :r, :polar (or :θ, :theta), and :azi (or :φ, :phi, :azimuth). If an invalid property is specified, an error is raised.

function Base.setproperty!(x::CartesianCoordinates{T, dim}, i::Symbol, val) where {T <: Real, dim}

Sets the property i of the CartesianCoordinates{T, dim} instance x to the value val. The properties include :dim, :xs, and coordinate values like :x, :y, :z, or :xN for dimensions greater than 3. If an invalid property is specified, an error is raised.

function Base.show(io::IO, x::Coordinates)

Displays the Coordinates{T, dim} instance x in a human-readable format. The output includes the type of coordinates, the type of the coordinate values, and the dimension.

function trunc_dim(x::CartesianCoordinates{T, dim}, tdim) where {T <: Real, dim}

Truncates the dimension of a CartesianCoordinates{T, dim} instance x by removing the coordinate at index tdim. The resulting coordinates are returned as a new CartesianCoordinates instance with one less dimension.

@forward T.x functions...

Define methods for functions on type T, which call the relevant function on the field x.

Example

struct Wrapper
    x
end

@forward Wrapper.x  Base.sqrt                                  # now sqrt(Wrapper(4.0)) == 2.0
@forward Wrapper.x  Base.length, Base.getindex, Base.iterate   # several forwarded functions are put in a tuple
@forward Wrapper.x (Base.length, Base.getindex, Base.iterate)  # equivalent to above

@forward_binary T.x functions...

See @forward, but for functions with (first) two arguments of type T, e.g. Base.isequal.

@forward_binary_preserve_type T.x functions...

See @forward and @forward_binary, but for functions, that return a result with the same type as the inputs, e.g. Base.:(+). Works only, if function changes exactly one field! Resulting type is inferred using promote_type, which might fail in certain cases. Just try not mixing field types.