Merge branch 'main' into galran/issue146

microsoft · Apr 27, 2021 · 391ac12 · 391ac12
2 parents fe1f2b7 + 9595f11
commit 391ac12
Show file tree

Hide file tree

Showing 17 changed files with 906 additions and 1,687 deletions.
diff --git a/Project.toml b/Project.toml
@@ -2,7 +2,7 @@ name = "OpticSim"
 uuid = "24114763-4efb-45e7-af0e-cde916beb153"
 authors = ["Brian Guenter", "Charlie Hewitt", "Ran Gal", "Alfred Wong"]
 repository = "https://github.com/microsoft/OpticSim.jl"
-version = "0.4.4"
+version = "0.5.0-DEV"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,4 +1,5 @@
 [deps]
+CodeTracking = "da1fd8a2-8d9e-5ec2-8556-3022fb5608a2"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"

diff --git a/docs/make.jl b/docs/make.jl
@@ -23,7 +23,6 @@ makedocs(
         "Optical" => [
             "Systems" => "systems.md",
             "Emitters" => "emitters.md",
-            "Emitters (NEW)" => "emitters_new.md",
             "Interfaces" => "interfaces.md",
             "Lenses" => "lenses.md"
         ],

diff --git a/docs/src/emitters.md b/docs/src/emitters.md
@@ -1,87 +1,307 @@
 # Emitters
 
-Emitters create rays in a certain pattern, usually controlled by some parameters.
-The are constructed in a modular way, e.g.
+!!! warning
+    **The old emitter implementation is deprecated as of v0.5!** See below for the new API.
 
+Emitters create rays in a certain pattern, usually controlled by some parameters. Emitters are defined by Pixels and Spatial Layouts, and have a spectrum and an optical power distribution over the hemisphere. These are intrinsic physical properties of the emitter.
+
+The **basic emitter** ([`Source`](@ref sources)) is constructed as a combination of 4 basic elements and a 3D [`Transform`](@ref). The basic elements include:
+- [`Spectrum`](@ref spectrum)
+- [`Angular Power Distribution`](@ref angular_power_distribution)
+- [`Rays Origins Distribution`](@ref rays_origins_distribution)
+- [`Rays Directions Distribution`](@ref rays_directions_distribution)
+
+The [`OpticSim`](index.html) package comes with various implementations of each of these basic elements:
+- Spectrum - the **generate** interface returns a tuple (power, wavelength)
+  * [`Emitters.Spectrum.Uniform`](@ref) - A flat spectrum bounded (default: from 450nm to 680nm). the range is sampled uniformly.
+  * [`Emitters.Spectrum.DeltaFunction`](@ref) - Constant wave length.
+  * [`Emitters.Spectrum.Measured`](@ref) - measured spectrum to compute emitter power and wavelength (created by reading CSV files – more details will follow).
+- Angular Power Distribution - the interface **apply** returns an OpticalRay with modified power
+  * [`Emitters.AngularPower.Lambertian`](@ref)
+  * [`Emitters.AngularPower.Cosine`](@ref)
+  * [`Emitters.AngularPower.Gaussian`](@ref)
+- Rays Origins Distribution - the interface **length** returns the number of samples, and **generate** returns the n'th sample.
+  * [`Emitters.Origins.Point`](@ref) - a single point
+  * [`Emitters.Origins.RectUniform`](@ref) - a uniformly sampled rectangle with user defined number of samples
+  * [`Emitters.Origins.RectGrid`](@ref) - a rectangle sampled in a grid fashion
+  * [`Emitters.Origins.Hexapolar`](@ref) - a circle (or an ellipse) sampled in an hexapolar fashion (rings)
+- Rays Directions Distribution - the interface **length** returns the number of samples, and **generate** returns the n'th sample.
+  * [`Emitters.Directions.Constant`](@ref)
+  * [`Emitters.Directions.RectGrid`](@ref)
+  * [`Emitters.Directions.UniformCone`](@ref)
+  * [`Emitters.Directions.HexapolarCone`](@ref)
+
+## [Examples of Basic Emitters](@id basic_emitters)
+
+**Note**: All of the examples on this page assume that the following statement was executed:
+
+```@example
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters
+```
+
+### Point origin with various Direction distributions
 ```@example
-using OpticSim, StaticArrays # hide
-Vis.draw(UniformOpticalSource(CollimatedSource(HexapolarOriginPoints(4, 1.0, 1.0, position = SVector(0.0, 0.0, 10.0), direction = SVector(0.0, sind(30), -cosd(30)))), 0.55))
-Vis.save("assets/source1.png") # hide
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+src = Sources.Source(origins=Origins.Point(), directions=Directions.RectGrid(π/4, π/4, 15, 15))
+Vis.draw(src, debug=true)
+Vis.save("assets/emitters_example_rect_grid.png") # hide
 nothing #hide
 ```
 
-![Emitter example 1 image](assets/source1.png)
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_rect_grid.png">
+    <img width="250" src="../assets/emitters_example_rect_grid.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+An example of <b>RectGrid</b> Direction Distribution
+</td>
+</tr></table>
+```
 
 ```@example
-using OpticSim, StaticArrays # hide
-Vis.draw(UniformOpticalSource(GridSource(OriginPoint{Float64}(1, position = SVector(0.0, 0.0, 10.0), direction = SVector(0.0, 0.0, -1.0)), 5, 5, π / 4, π / 4), 0.65))
-Vis.save("assets/source2.png") # hide
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+src = Sources.Source(origins=Origins.Point(), directions=Directions.UniformCone(π/6, 1000))
+Vis.draw(src, debug=true)
+Vis.save("assets/emitters_example_uniform_cone.png") # hide
 nothing #hide
 ```
 
-![Emitter example 2 image](assets/source2.png)
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_uniform_cone.png">
+    <img width="250" src="../assets/emitters_example_uniform_cone.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+An example of <b>UniformCone</b> Direction Distribution with 1000 sampled directions
+</td>
+</tr></table>
+```
 
 ```@example
-using OpticSim, StaticArrays # hide
-Vis.draw(CosineOpticalSource(RandomSource(OriginPoint{Float64}(200, direction = SVector(0.0, 0.0, 1.0))), 1.0, 0.45))
-Vis.save("assets/source3.png") # hide
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+src = Sources.Source(origins=Origins.Point(), directions=Directions.HexapolarCone(π/6, 10))
+Vis.draw(src, debug=true)
+Vis.save("assets/emitters_example_hexapolar_cone.png") # hide
 nothing #hide
 ```
 
-![Emitter example 3 image](assets/source3.png)
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_hexapolar_cone.png">
+    <img width="250" src="../assets/emitters_example_hexapolar_cone.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+An example of <b>HexapolarCone</b> Direction Distribution
+</td>
+</tr></table>
+```
 
-## Rays
+### Various origins distributions
 
-```@docs
-Ray
-OpticalRay
-OpticSim.generateray
+```@example
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+src = Sources.Source(origins=Origins.RectGrid(1.0, 1.0, 10, 10), directions=Directions.Constant())
+Vis.draw(src, debug=true)
+Vis.save("assets/emitters_example_origin_rectgrid.png") # hide
+nothing #hide
+```
+
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_origin_rectgrid.png">
+    <img width="250" src="../assets/emitters_example_origin_rectgrid.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+An example of <b>RectGrid</b> origin distribution
+</td>
+</tr></table>
+```
+
+```@example
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+src = Sources.Source(origins=Origins.Hexapolar(5, 1.0, 2.0), directions=Directions.Constant())
+Vis.draw(src, debug=true)
+Vis.save("assets/emitters_example_origin_hexapolar.png") # hide
+nothing #hide
+```
+
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_origin_hexapolar.png">
+    <img width="250" src="../assets/emitters_example_origin_hexapolar.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+An example of <b>Hexapolar</b> origin distribution
+</td>
+</tr></table>
+```
+
+### Examples of Angular Power Distribution
+
+In these example, the arrow width is proportional to the ray power.
+
+```@example
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+src = Sources.Source(
+    origins=Origins.Hexapolar(1, 8.0, 8.0),             # Hexapolar Origins
+	directions=Directions.RectGrid(π/6, π/6, 15, 15),   # RectGrid Directions
+	power=AngularPower.Cosine(10.0)                     # Cosine Angular Power 
+)
+Vis.draw(src, debug=true)
+Vis.save("assets/emitters_example_angular1.png") # hide
+nothing #hide
 ```
 
-## Origin Points
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_angular1.png">
+    <img width="250" src="../assets/emitters_example_angular1.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+An example of <b>Cosine</b> angular power distribution
+</td>
+</tr></table>
+```
+
+```@example
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+src = Sources.Source(
+	origins=Origins.RectGrid(1.0, 1.0, 3, 3),           # RectGrid Origins  
+	directions=Directions.HexapolarCone(π/6, 10),       # HexapolarCone Directions
+	power=AngularPower.Gaussian(2.0, 2.0)               # Gaussian Angular Power 
+)
+Vis.draw(src, debug=true)
+Vis.save("assets/emitters_example_angular2.png") # hide
+nothing #hide
+```
+
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_angular2.png">
+    <img width="250" src="../assets/emitters_example_angular2.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+An example of <b>Gaussian</b> angular power distribution
+</td>
+</tr></table>
+```
+
+### Composite Sources - Display Example
+
+```@example
+using OpticSim, OpticSim.Geometry, OpticSim.Emitters # hide
+
+# construct the emitter's basic components
+S = Spectrum.Uniform()
+P = AngularPower.Lambertian()
+O = Origins.RectGrid(1.0, 1.0, 3, 3)
+D = Directions.HexapolarCone(deg2rad(5.0), 3)	
+	
+# construct the source. in this example a "pixel" source will contain only one source as we are simulating a "b/w" display. 
+# for RGB displays we can combine 3 sources to simulate "a pixel".
+Tr = Transform(Vec3(0.5, 0.5, 0.0))
+source1 = Sources.Source(Tr, S, O, D, P)
+	
+# create a list of pixels - each one is a composite source
+pixels = Vector{Sources.CompositeSource{Float64}}(undef, 0)
+for y in 1:5 # image_height
+    for x in 1:10 # image_width
+        # pixel position relative to the display's origin
+        local pixel_position = Vec3((x-1) * 1.1, (y-1) * 1.5, 0.0)
+        local Tr = Transform(pixel_position)
+
+        # constructing the "pixel"
+        pixel = Sources.CompositeSource(Tr, [source1])
+
+        push!(pixels, pixel)
+    end
+end
+	
+Tr = Transform(Vec3(0.0, 0.0, 0.0))
+my_display = Sources.CompositeSource(Tr, pixels)
+
+Vis.draw(my_display)                                                # render the display - nothing but the origins primitives
+rays = AbstractArray{OpticalRay{Float64, 3}}(collect(my_display))   # collect the rays generated by the display
+Vis.draw!(rays)                                                     # render the rays 
+
+Vis.save("assets/emitters_example_composite_display.png") # hide
+nothing #hide
+```
+
+```@raw html
+<table><tr>
+<td>
+<a target="_blank" href="../assets/emitters_example_composite_display.png">
+    <img width="500" src="../assets/emitters_example_composite_display.png" style="max-width:100%;">
+</a>
+</td>
+<td valign="middle">
+A display example using composite sources.
+</td>
+</tr></table>
+```
+
+
+
+## [Spectrum](@id spectrum)
 
 ```@docs
-OpticSim.RayOriginGenerator
-RandomRectOriginPoints
-GridRectOriginPoints
-RandomEllipseOriginPoints
-HexapolarOriginPoints
-OriginPoint
-OpticSim.genorigin
+Emitters.Spectrum.Uniform
+Emitters.Spectrum.DeltaFunction
+Emitters.Spectrum.Measured
+Emitters.Spectrum.spectrumpower
 ```
 
-## Directions
+## [Angular Power Distribution](@id angular_power_distribution)
 
 ```@docs
-GeometricRayGenerator
-CollimatedSource
-GridSource
-RandomSource
-OpticSim.gendirection
+Emitters.AngularPower.Lambertian
+Emitters.AngularPower.Cosine
+Emitters.AngularPower.Gaussian
 ```
 
-## Power
+## [Rays Origins Distribution](@id rays_origins_distribution)
 
 ```@docs
-OpticalRayGenerator
-UniformOpticalSource
-CosineOpticalSource
-GaussianOpticalSource
+Emitters.Origins.Point
+Emitters.Origins.RectUniform
+Emitters.Origins.RectGrid
+Emitters.Origins.Hexapolar
 ```
 
-## Compound
+## [Rays Directions Distribution](@id rays_directions_distribution)
 
 ```@docs
-PixelSource
-OpticalSourceArray
-BasicDisplayPanel
-OpticalSourceGroup
-RayListSource
+Emitters.Directions.Constant
+Emitters.Directions.RectGrid
+Emitters.Directions.UniformCone
+Emitters.Directions.HexapolarCone
 ```
 
-## Fields
+## [Sources](@id sources)
 
 ```@docs
-HexapolarField
-GridField
+Emitters.Sources.Source
+Emitters.Sources.CompositeSource
 ```
+
+
+
+
+
+