From 0ccdd530f164d3f98d220d1e97e41c9853bfe646 Mon Sep 17 00:00:00 2001
From: ffreyer <frederic481994@hotmail.de>
Date: Thu, 11 Jan 2024 21:13:02 +0100
Subject: [PATCH] tests & docs

---
 MakieCore/src/basic_plots.jl           |  2 +-
 ReferenceTests/src/tests/primitives.jl |  7 ++++++-
 docs/reference/plots/voxel.md          | 17 +++++++++++++++++
 test/primitives.jl                     |  6 +++---
 4 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/MakieCore/src/basic_plots.jl b/MakieCore/src/basic_plots.jl
index 1cae61e0cc6..ae7ffe87816 100644
--- a/MakieCore/src/basic_plots.jl
+++ b/MakieCore/src/basic_plots.jl
@@ -525,7 +525,7 @@ representation and may behave a bit differently than usual.
 - `uvmap = nothing` defines a map from voxel ids (and optionally sides) to uv coordinates. These uv coordinates are then
   used to sample a 2D texture passed through `color` for texture mapping.
 - `interpolate = false` controls whether the texture map is sampled with interpolation (i.e. smoothly) or not (i.e. pixelated).
-- `gap = 0.0` sets the gap between voxels.
+- `gap = 0.0` sets the gap between adjacent voxels in units of the voxel size. This needs to be larger than 0.01 to take effect.
 - `_limits`: Internal attribute for keeping track of `extrema(chunk)`.
 - `_local_update`: Internal attribute for communicating updates to the backend.
 
diff --git a/ReferenceTests/src/tests/primitives.jl b/ReferenceTests/src/tests/primitives.jl
index bbb6a112bfb..9202628d2dd 100644
--- a/ReferenceTests/src/tests/primitives.jl
+++ b/ReferenceTests/src/tests/primitives.jl
@@ -538,4 +538,9 @@ end
     a2, _ = voxels(fig[1,2], chunk, lowclip = :red, highclip = :red, colorrange = (1.1, 899.9), shading = NoShading)
     foreach(a -> update_cam!(a.scene, Vec3f(0, 0, 40), Vec3f(0), Vec3f(0,1,0)), (a1, a2))
     fig
-end
\ No newline at end of file
+end
+
+@reference_test "Voxel - gap attribute" begin
+    # test direct mapping of ids to colors & upsampling of vector colormap
+    voxels(rand(3,3,3), gap = 0.3)
+end
diff --git a/docs/reference/plots/voxel.md b/docs/reference/plots/voxel.md
index e7244b78b61..4c33e72029d 100644
--- a/docs/reference/plots/voxel.md
+++ b/docs/reference/plots/voxel.md
@@ -25,6 +25,23 @@ f, a, p = voxels(-1..1, -1..1, -1..1, cube_with_holes, is_air = x -> !(1.65 <= x
 \end{examplefigure}
 
 
+#### Gap Attribute
+
+The `gap` attribute allows you to specify a gap size between adjacent voxels.
+It is given in units of the voxel size (at `gap = 0`) so that `gap = 0` creates no gaps and `gap = 1` reduces the voxel size to 0.
+Note that this attribute only takes effect at values `gap > 0.01`.
+
+\begin{examplefigure}{}
+```julia
+using GLMakie
+GLMakie.activate!() # hide
+
+chunk = reshape(collect(1:27), 3, 3, 3)
+voxels(chunk, gap = 0.33)
+```
+\end{examplefigure}
+
+
 #### Color and the internal representation
 
 Voxels are represented as an `Array{UInt8, 3}` of voxel ids internally.
diff --git a/test/primitives.jl b/test/primitives.jl
index 9325f3881ee..c4bd221fd7d 100644
--- a/test/primitives.jl
+++ b/test/primitives.jl
@@ -27,7 +27,7 @@ end
     f, a, p = voxels(
         data,
         lowclip = RGBf(1, 0, 1), highclip = RGBf(0, 1, 0),
-        colormap = [RGBf(0, 0, 0), RGBf(1, 1, 1)]
+        colormap = [RGBf(0, 0, 0), RGBf(1, 1, 1)], gap = 0.1
     )
 
     # data conversion pipeline
@@ -53,8 +53,8 @@ end
     @test cc.colormap[][end] == RGBAf(0,1,0,1)
 
     # voxels-as-meshscatter helpers
-    @test Makie.voxel_size(p) ≈ Vec3f(1)
-    ps = [Point3f(x - 3, y - 2.5, z - 2) for z in 0:3 for y in 0:4 for x in 0:5]
+    @test Makie.voxel_size(p) ≈ Vec3f(0.9)
+    ps = [Point3f(x - 2.5, y - 2.0, z - 1.5) for z in 0:3 for y in 0:4 for x in 0:5]
     @test Makie.voxel_positions(p) ≈ ps
     @test Makie.voxel_colors(p) == cc.colormap[][p.converted[end][][:]]
 end