Beam groups (#12)

* move non-psf changes to seperate branch

* finalize miniscope tutorial

Author: StackEnjoyer

Project.toml

@@ -1,12 +1,12 @@
 name = "BeamletOptics"
 uuid = "c387492b-ffec-4e51-9a46-bd230226031c"
 authors = ["Hugo Uittenbosch <hugo.uittenbosch@dlr.de>, Oliver Kliebisch <oliver.kliebisch@dlr.de> and Thomas Dekorsy <thomas.dekorsy@dlr.de>"]
-version = "0.9.0"
-
+version = "0.10.0"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 GeometryBasics = "5c1252a2-5f33-56bf-86c9-59e7332b4326"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -26,6 +26,7 @@ BeamletOpticsMakieExt = "Makie"
 AbstractTrees = "0.4"
 Aqua = "0.8"
 FileIO = "1"
+ForwardDiff = "0.10, 1.0.1"
 GeometryBasics = "0.5"
 InteractiveUtils = "1"
 LinearAlgebra = "1"

docs/src/assets/beam_renders/beam_showcase.jl

@@ -52,12 +52,12 @@ render!(ax, m2)
 render!(ax, m3)
 render!(ax, prism; color=RGBAf(1, 1, 1, .25))
 
-arrow!(ax, BMO.position(first(BMO.rays(beam))), BMO.direction(first(BMO.rays(beam))); scale=2)
+arrow!(ax, position(first(BMO.rays(beam))), BMO.direction(first(BMO.rays(beam))); scale=2)
 
 
 for _ray in BMO.rays(beam)
     dir = BMO.direction(_ray)
-    pos = BMO.position(_ray)
+    pos = position(_ray)
     arrow!(ax, pos, dir; scale=2)
 end
 

docs/src/assets/beam_renders/collimated_sc.jl

@@ -0,0 +1,27 @@
+using GLMakie, BeamletOptics
+
+GLMakie.activate!(; ssao=true)
+
+const BMO = BeamletOptics
+
+include(joinpath(@__DIR__, "..", "render_utils.jl"))
+
+## collimated source
+cs = CollimatedSource([0,0,0], [0,1,0], 15e-3; num_rings=3, num_rays=200)
+
+cs_fig = Figure(; size=(600,200))
+display(cs_fig)
+cs_ax = LScene(cs_fig[1,1])
+hide_axis(cs_ax)
+
+render!(cs_ax, cs, show_pos=true, flen=0.05, color=:red, render_every=1)
+
+cs_view = [
+    0.26513     0.964213    7.68482e-16  -0.0180273
+    0.0488896  -0.0134432   0.998714      0.00108822
+    0.962972   -0.264789   -0.0507042    -0.025119
+    0.0         0.0         0.0           1.0
+]
+
+set_view(cs_ax, cs_view)
+save("collimated_beam_source.png", cs_fig; px_per_unit=8, update = false)

docs/src/assets/beam_renders/pointsource_sc.jl

@@ -0,0 +1,27 @@
+using GLMakie, BeamletOptics
+
+GLMakie.activate!(; ssao=true)
+
+const BMO = BeamletOptics
+
+include(joinpath(@__DIR__, "..", "render_utils.jl"))
+
+## point source
+ps = PointSource([0,0,0], [0,1,0], deg2rad(10); num_rings=3, num_rays=200)
+
+ps_fig = Figure(; size=(600,200))
+display(ps_fig)
+ps_ax = LScene(ps_fig[1,1])
+hide_axis(ps_ax)
+
+render!(ps_ax, ps, show_pos=true, flen=0.1, color=:red)
+
+ps_view = [
+    0.00272773   0.999996     5.03287e-16  -0.0584386
+    0.424361    -0.00115755   0.905492      2.95341e-5
+    0.905489    -0.00246994  -0.424362     -0.04708
+    0.0          0.0          0.0           1.0
+]
+
+set_view(ps_ax, ps_view)
+save("point_beam_source.png", ps_fig; px_per_unit=8, update = false)

docs/src/assets/mi_assets/michelson_plots.jl

@@ -130,7 +130,7 @@ hidedecorations!(heat2)
 hm = heatmap!(heat1, pd.x*1e3, pd.y*1e3, BeamletOptics.intensity(pd), colormap=:viridis)
 
 zrotate3d!(m1, 1e-3)
-BeamletOptics.reset_detector!(pd)
+empty!(pd)
 solve_system!(system, beam)
 
 hm = heatmap!(heat2, pd.x*1e3, pd.y*1e3, BeamletOptics.intensity(pd), colormap=:viridis)
@@ -148,7 +148,7 @@ n = 100
 P = zeros(n+1)
 
 for i in eachindex(P)
-    BeamletOptics.reset_detector!(pd)
+    empty!(pd)
     solve_system!(system, beam)
     P[i] = BeamletOptics.optical_power(pd)
     # translate by Δy

docs/src/assets/ms_assets/miniscope_showcase.jl

@@ -50,7 +50,7 @@ function objective_lens_2()
     surf_3 = SphericalSurface(-5.020mm, 2*2.380mm)
     dl11 = Lens(surf_1, surf_2, 0.5mm, NSF4)
     dl12 = Lens(surf_2, surf_3, 2.5mm, NLAK22)
-    translate3d!(dl12, [0, BMO.thickness(dl11), 0])
+    translate3d!(dl12, [0, thickness(dl11), 0])
     obj_lens_2 = DoubletLens(dl11, dl12)
     return obj_lens_2
 end
@@ -62,7 +62,7 @@ function tube_doublet()
     surf_3 = SphericalSurface(-14.413mm, 2*2.812mm, 2*3mm)
     dl21 = Lens(surf_1, surf_2, 3.4mm, NLAK22)
     dl22 = Lens(surf_2, surf_3, 1.0mm, NSF4)
-    translate3d!(dl22, [0, BMO.thickness(dl21), 0])
+    translate3d!(dl22, [0, thickness(dl21), 0])
     tube_lens = DoubletLens(dl21, dl22)
     return tube_lens
 end
@@ -71,8 +71,8 @@ function objective_group()
     obj_lens_1 = objective_lens_1()
     obj_lens_2 = objective_lens_2()
     tube_lens = tube_doublet()
-    translate_to3d!(obj_lens_2, [0, BMO.position(obj_lens_1)[2] + BMO.thickness(obj_lens_1) + 3.344mm, 0])
-    translate_to3d!(tube_lens, [0, BMO.position(obj_lens_2)[2] + BMO.thickness(obj_lens_2) + 2mm, 0])
+    translate_to3d!(obj_lens_2, [0, position(obj_lens_1)[2] + thickness(obj_lens_1) + 3.344mm, 0])
+    translate_to3d!(tube_lens, [0, position(obj_lens_2)[2] + thickness(obj_lens_2) + 2mm, 0])
     _objective_group = ObjectGroup([obj_lens_1, obj_lens_2, tube_lens])
     xrotate3d!(_objective_group, deg2rad(90))
     return _objective_group
@@ -106,8 +106,8 @@ function collection_group()
         NLASF44
     )
 
-    translate3d!(collect_lens, [0, BMO.position(ef_1)[2] + BMO.thickness(ef_1) + 0.1mm, 0])
-    translate3d!(ef_2, [0, BMO.position(collect_lens)[2] + BMO.thickness(collect_lens) + 0.25mm, 0])
+    translate3d!(collect_lens, [0, position(ef_1)[2] + thickness(ef_1) + 0.1mm, 0])
+    translate3d!(ef_2, [0, position(collect_lens)[2] + thickness(collect_lens) + 0.25mm, 0])
 
     collect_group = ObjectGroup([ef_1, collect_lens, ef_2])
 
@@ -117,7 +117,7 @@ function collection_group()
     return collect_group
 end
 
-optical_system() = System([objective_group(), dichroic_splitter(), collection_group()])
+optical_system_group() = ObjectGroup([objective_group(), dichroic_splitter(), collection_group()])
 
 ##
 miniscope = miniscope_body()
@@ -175,7 +175,7 @@ c_view = [
 set_view(ax, c_view)
 save("objective_lens_1.png", fig; px_per_unit=8, update = false)
 
-##
+## lens 2 render
 fig = Figure(size=(600, 200)) 
 display(fig)
 ax = LScene(fig[1,1])
@@ -201,8 +201,8 @@ set_view(ax, c_view)
 save("objective_lens_2.png", fig; px_per_unit=8, update = false)
 
 ## full group render
-translate_to3d!(obj_lens_2, [0, BMO.position(obj_lens_1)[2] + BMO.thickness(obj_lens_1) + 3.344mm, 0])
-translate_to3d!(tube_lens, [0, BMO.position(obj_lens_2)[2] + BMO.thickness(obj_lens_2) + 2mm, 0])
+translate_to3d!(obj_lens_2, [0, position(obj_lens_1)[2] + thickness(obj_lens_1) + 3.344mm, 0])
+translate_to3d!(tube_lens, [0, position(obj_lens_2)[2] + thickness(obj_lens_2) + 2mm, 0])
 
 fig = Figure(size=(600, 300))
 display(fig)
@@ -212,9 +212,9 @@ render!(ax, obj_lens_1, transparency=true, color=lens_color(0.5))
 render!(ax, obj_lens_2, transparency=true, color=lens_color(0.5))
 render!(ax, tube_lens, transparency=true, color=lens_color(0.5))
 
-tp1 = BMO.position(obj_lens_1) + [0, -.5mm, 2mm]
-tp2 = BMO.position(obj_lens_2) + [0, .2mm, 3mm]
-tp3 = BMO.position(tube_lens) + [0, 1.3mm, 4mm]
+tp1 = position(obj_lens_1) + [0, -.5mm, 2mm]
+tp2 = position(obj_lens_2) + [0, .2mm, 3mm]
+tp3 = position(tube_lens) + [0, 1.3mm, 4mm]
 
 text!(tp1, text="obj_lens_1")
 text!(tp2, text="obj_lens_2")
@@ -234,7 +234,7 @@ c_view = [
 set_view(ax, c_view)
 save("full_objective_lens.png", fig; px_per_unit=8, update = false)
 
-##
+## full optical system render
 fig = Figure(size=(600,400))
 display(fig)
 ax = LScene(fig[1,1])
@@ -251,4 +251,39 @@ c_view = [
 ]
 
 set_view(ax, c_view)
-save("full_optical_system.png", fig; px_per_unit=8, update = false)
+save("full_optical_system.png", fig; px_per_unit=8, update = false)
+
+##
+osg = optical_system_group()
+system = System([osg])
+
+# for tutorial
+ps_green = PointSource([0, 0, -0.5mm], [0, 0, 1], deg2rad(20), λ_green, num_rays=1000, num_rings=5)
+ps_red =   PointSource([0, 0, -0.5mm], [0, 0, 1], deg2rad(30), λ_red,   num_rays=1000, num_rings=5)
+
+solve_system!(system, ps_green)
+solve_system!(system, ps_red)
+
+##
+fig = Figure(size=(600,200))
+ax = LScene(fig[1,1])
+hide_axis(ax)
+
+render!(ax, system; color=lens_color())
+render!(ax, ps_green;   color=RGBAf(0,1,0,1.00), render_every=5, flen=3mm, show_pos=false)
+render!(ax, ps_red;     color=RGBAf(1,0,0,0.25), render_every=5, flen=3mm, show_pos=false)
+
+display(fig)
+
+set_orthographic(ax)
+
+c_view = [
+  0  0   1 -0.015
+  0 -1   0  0
+  1  0   0 -0.55
+  0  0   0  1
+]
+
+set_view(ax, c_view)
+
+save("miniscope_trace.png", fig; px_per_unit=8, update = false)

docs/src/assets/ms_assets/ucla.jl

@@ -38,7 +38,7 @@ surf_3 = SphericalSurface(-5.020mm, 2*2.380mm)
 dl11 = Lens(surf_1, surf_2, 0.5mm, NBK7)
 dl12 = Lens(surf_2, surf_3, 2.5mm, NBK7)
 
-translate3d!(dl12, [0, BMO.thickness(dl11), 0])
+translate3d!(dl12, [0, thickness(dl11), 0])
 
 obj_lens_2 = DoubletLens(dl11, dl12)
 
@@ -58,13 +58,13 @@ end
 dl21 = Lens(surf_1, surf_2, 3.4mm, NBK7)
 dl22 = Lens(surf_2, surf_3, 1.0mm, NBK7)
 
-translate3d!(dl22, [0, BMO.thickness(dl21), 0])
+translate3d!(dl22, [0, thickness(dl21), 0])
 
 tube_lens = DoubletLens(dl21, dl22)
 
 ## Objective group
-translate_to3d!(obj_lens_2, [0, BMO.position(obj_lens_1)[2] + BMO.thickness(obj_lens_1) + 3.344mm, 0])
-translate_to3d!(tube_lens, [0, BMO.position(obj_lens_2)[2] + BMO.thickness(obj_lens_2) + 2mm, 0])
+translate_to3d!(obj_lens_2, [0, position(obj_lens_1)[2] + thickness(obj_lens_1) + 3.344mm, 0])
+translate_to3d!(tube_lens, [0, position(obj_lens_2)[2] + thickness(obj_lens_2) + 2mm, 0])
 
 objective_group = ObjectGroup([obj_lens_1, obj_lens_2, tube_lens])
 
@@ -91,8 +91,8 @@ collect_lens = Lens(
     NBK7
 )
 
-translate3d!(collect_lens, [0, BMO.position(ef_1)[2] + BMO.thickness(ef_1) + 0.1mm, 0])
-translate3d!(ef_2, [0, BMO.position(collect_lens)[2] + BMO.thickness(collect_lens) + 0.25mm, 0])
+translate3d!(collect_lens, [0, position(ef_1)[2] + thickness(ef_1) + 0.1mm, 0])
+translate3d!(ef_2, [0, position(collect_lens)[2] + thickness(collect_lens) + 0.25mm, 0])
 
 collect_group = ObjectGroup([ef_1, collect_lens, ef_2])
 

docs/src/assets/ray_renders/ray_showcase.jl

@@ -31,7 +31,7 @@ zrotate3d!(cube, deg2rad(-30))
 
 ray_pos = [0mm,5mm,5mm]
 ray_pos = [5mm,1mm,10mm]
-ray_dir = BMO.position(cube) - ray_pos + [5mm, 0, 1mm]
+ray_dir = position(cube) - ray_pos + [5mm, 0, 1mm]
 ray = Ray(ray_pos, ray_dir)
 
 ray_dir = BMO.direction(ray)

docs/src/assets/spotdetector_showcase.jl

@@ -24,34 +24,30 @@ render!(system_ax, system)
 beam = Beam([0,-50mm,0], [0,1,0], 1e-6)
 
 aperture = BeamletOptics.inch*0.8
+num_rings = 20
+num_rays = 5000
 
-zs = LinRange(-aperture/2, aperture/2, 25)
+cs = CollimatedSource([0,-50mm,0], [0,1,0], aperture, 1e-6; num_rings, num_rays)
 
-for z in zs
-    x = BeamletOptics.position(first(beam.rays))[1]
-    y = BeamletOptics.position(first(beam.rays))[2]
-    BeamletOptics.position!(first(beam.rays), Point3{Float64}(x, y, z))
-    solve_system!(system, beam)
-    render!(system_ax, beam, show_pos=true)
+t1 = @timed solve_system!(system, cs)
+
+for i = 1:50:length(BeamletOptics.beams(cs))
+    render!(system_ax, BeamletOptics.beams(cs)[i], color=:blue, show_pos=true)
 end
 
 ## render diagram
-n_rings = 20
-n_rays = 5000
-BeamletOptics.create_spot_diagram(system, beam, aperture; n_rings, n_rays)
-# Rerun for time without compile
-t1 = @timed BeamletOptics.create_spot_diagram(system, beam, aperture; n_rings, n_rays)
-
 spot_fig = Figure(size=(600,400))
 spot_ax = Axis(spot_fig[1,1], aspect=1, xlabel="x [mm]", ylabel="y [mm]")
 sc = scatter!(spot_ax, sd.data, markersize=3, color=:blue)
 
 extime = trunc(t1.time*1e3, digits=2)
 
 leg_string = "
-   # of traces: $n_rays \n
-   # of rings: $n_rings \n
+   # of traces: $num_rays \n
+   # of rings: $num_rings \n
    Ex. Time: $extime ms \n
 "
 
-Legend(spot_fig[1,2], [sc], [leg_string], "Quick stats.")
+Legend(spot_fig[1,2], [sc], [leg_string], "Quick stats.")
+
+spot_fig

docs/src/basics/beams.md

@@ -3,6 +3,8 @@ beam_showcase_dir = joinpath(@__DIR__, "..", "assets", "beam_renders")
 
 include(joinpath(beam_showcase_dir, "beam_showcase.jl"))
 include(joinpath(beam_showcase_dir, "gb_showcase.jl"))
+include(joinpath(beam_showcase_dir, "collimated_sc.jl"))
+include(joinpath(beam_showcase_dir, "pointsource_sc.jl"))
 ```
 
 # Beams
@@ -23,6 +25,39 @@ A ray tracing example through an arbitrary system using a [`Beam`](@ref) is show
 
 ![Beam structure](beam_showcase.png)
 
+## Beam groups
+
+For convenience, the [`BeamletOptics.AbstractBeamGroup`](@ref) offers a container-like interface for groups of [`Beam`](@ref)s as commonly used in other software packages. The following concrete implementations are currently provided:
+
+```@repl
+using BeamletOptics # hide
+BeamletOptics.list_subtypes(BeamletOptics.AbstractBeamGroup);
+```
+
+Refer to the following sections for convenience constructors to generate the sources listed above.
+
+### Collimated beam source
+
+The collimated beam source is ideal to model light coming from a focal plane at infinity. This is useful for simulating plane wavefronts. You can define a collimated monochromatic [`Beam`](@ref) source as follows:
+
+```@docs; canonical=false
+CollimatedSource(::AbstractArray{<:Real}, ::AbstractArray{<:Real}, ::Real, ::Real)
+```
+
+![Collimated group of beams](collimated_beam_source.png)
+
+### Point beam source
+
+The `PointSource` type is used to model emission from a spatially localized source that radiates [`Beam`](@ref)s in a range of directions. This is commonly used to simulate conical emission patterns, such as light emerging from a fiber tip or a light source for a lens objective with a known focal distance. You can specify the origin and a propagation direction, which are then used to construct the monochromatic `PointSource`.
+
+```@docs; canonical=false
+PointSource(::AbstractArray{<:Real}, ::AbstractArray{<:Real}, ::Real, ::Real)
+```
+
+Below you can find an exemplary illustration of a `PointSource`.
+
+![Point source of beams](point_beam_source.png)
+
 ## Gaussian beamlet
 
 Lasers are common devices in modern optical laboratories. Modeling their propagation through an optical setup can be of interest when planning new experiments. Geometrical ray tracing struggles to capture the propagation of a laser beam correctly, since it can not inherently capture the wave nature of e.g. the [Gaussian beam](https://www.rp-photonics.com/gaussian_beams.html).