SphereSurfaceHistogram is a relatively small package that allows you to create a histogram of 3D unit vectors.
To use the package you need to first create an SSHBinner with some number of bins. The number of bins will then be optimized to give equally sized bins (in terms of the surface they occupy on a unit sphere). Once you have the binner you can happily push! or append! unit vectors.
using LinearAlgebra, SphereSurfaceHistogram
B = SSHBinner(1000) # optimizes to 978 bins
append!(B, [normalize(2 .* rand(3) .- 1) for _ in 1:1_000_000])
The package also contains some plotting utilities for Makie. Thanks to Requires.jl these will only be loaded when Makie is loaded. There are also a few functions for generating meshes which are loaded when GeometryBasics is available. You can check the docs for more information on this. Using the example above:
using GLMakie
histogram(B, outline=true)
If you wish to get less processed results from the binner you can index it with two angles theta and phi. This will return the count of the relevant bin. You can also use colons to trace a ring on the circle. For example, B[pi/2, :] will return the counts at z=0.
Some other notes:
push!andappend!are pretty fast, I think. In my benchmarks the time perpush!is about 30ns, probably scaling logarithmically with the number of bins. (I never explicitly checked) In the example aboveappend!is about 4x faster than the creation of random unit vectors.- The optimization of an
SSHBinneris deterministic. Two binners created with the same target bin count will produce matching bins. - The binner can be reconstructed from just the counts. For example, you can save just
B.binsand later reconstruct the binner viaSSHBinner(bins).