SphereSurfaceHistogram.jl
SphereSurfaceHistogram
is a package for binning 3D unit vectors. Each bin has the same size - i.e. it covers (approximately) the same (curved) area on a unit sphere.
There are currently two ways to bin values in the package. The first is SSHBinner
which simply counts how often a bin has been pushed to. The other is SSHAverager
which reports the average float value that has been pushed to a specific bin.
Quickstart
An empty binner with approximately 10_000
bins can be created with
julia> using SphereSurfaceHistogram
julia> binner = SSHBinner(10_000)
SSHBinner with 9810 bins
Adding vectors can be done using push!
or append!
julia> using SphereSurfaceHistogram
julia> binner = SSHBinner(10_000)
SSHBinner with 9810 bins
julia> push!(binner, [1.0, 0.0, 0.0])
julia> append!(binner, [[0.0, 1.0, 0.0], [0.0, 0.0, 1.0]])
SphereSurfaceHistogram does not verify that the given vector is normalized.
SSHAverager
works analogously:
julia> using SphereSurfaceHistogram
julia> binner = SSHAverager(10_000)
SSHAverager with 9810 bins
julia> push!(binner, [1.0, 0.0, 0.0], 1.6)
julia> append!(binner, [[0.0, 1.0, 0.0], [0.0, 0.0, 1.0]], [0.3, 0.6])
You can also push to a binner using angles of a spherical coordinate system. This follows the physics convention as mentioned on wikipedia, i.e. with $theta \in (0, pi)$ being the angle between the z axis and the vector and $phi \in (0, 2pi)$ extending counterclockwise from the x axis.
julia> using SphereSurfaceHistogram
julia> binner = SSHBinner(10_000)
SSHBinner with 9810 bins
julia> push!(binner, 0.5pi, 1.7pi) # theta, phi
SphereSurfaceHistogram does not verify that the given angles are in bounds.
Accessing the Histogram
SphereSurfaceHistogram provides custom getindex methods working with angles in radians.
Base.getindex
— Methodgetindex(B::SSHBinner, theta, phi)
Returns the height of the bin which includes angles phi ∈ (0, 2pi) and theta ∈ (0, pi).
Plotting
SphereSurfaceHistogram includes a couple of Makie recipes. Most notably is the histogram
recipe. It creates a mesh where each vertex represents a bin. Colors are then picked based on the counts in each bin.
The image above uses the following code
using SphereSurfaceHistogram, GLMakie
binner1 = SSHBinner(10_000)
binner2 = SSHBinner(10_000)
for _ in 1:1000
append!(binner1, random_unit_vector(1_000))
end
for _ in 1:1_000_000
push!(binner2, normalize(2rand(3) .- 1.0))
end
fig = Figure()
histogram(fig[1, 1], binner1)
histogram(fig[1, 2], binner2)
fig
Plotting methods are not loaded by default. SphereSurfaceHistogram makes use of Requires.jl
to dynamically load plotting related methods when Makie.jl
becomes available.
Mesh generation methods can also be loaded individually. If you want to use the mesh generation methods without Makie
, you should import GeometryBasics.jl
.