# \[ANN\] SphereSurfaceHistogram.jl

**URL:** <https://discourse.julialang.org/t/ann-spheresurfacehistogram-jl/57940>\
**Category:** Package Announcements\
**Tags:** package, announcement\
**Created:** [March 25, 2021, 3:38pm UTC](https://discourse.julialang.org/t/ann-spheresurfacehistogram-jl/57940 "2021-03-25T15:38:52Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![ffreyer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ffreyer/32/21569_2.png) [@ffreyer](https://discourse.julialang.org/u/ffreyer)\
**Post date:** [March 25, 2021, 3:38pm UTC](https://discourse.julialang.org/t/ann-spheresurfacehistogram-jl/57940/1 "2021-03-25T15:38:52Z")

</div>

[SphereSurfaceHistogram](https://github.com/ffreyer/SphereSurfaceHistogram.jl) 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.

```julia
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](https://ffreyer.github.io/SphereSurfaceHistogram.jl/dev/Plotting.html) for more information on this. Using the example above:

```julia
using GLMakie
histogram(B, outline=true)

```

 ![Screenshot from 2021-03-25 16-30-18](https://global.discourse-cdn.com/julialang/original/3X/f/d/fd339de7948d6c7d8d60babd1b4e72243e7db7b4.png)

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!` and `append!` are pretty fast, I think. In my benchmarks the time per `push!` is about 30ns, probably scaling logarithmically with the number of bins. (I never explicitly checked) In the example above `append!` is about 4x faster than the creation of random unit vectors.
- The optimization of an `SSHBinner` is 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.bins` and later reconstruct the binner via `SSHBinner(bins)`.