dcc-lab / raytracing Goto Github PK

There is a chief ray for every point on the object. However, the chief ray from the point on the object at the edge of the field of view is often referred to as "the chief ray". We may want to call it the System chief ray but I am not sure if this is correct
Same with marginal rays: there are marginal rays from all points, but the useful one is the one on axis at the object. We need to determine what the correct nomenclature is by checking in books:
Kloos, Saleh Teich, Smith, etc... and people in the field.

We need someone to write a procedure for writing tests and put it on the Wiki
at https://github.com/DCC-Lab/RayTracing/wiki/HOWTO-write-Unit-Tests

There was a problem with matplotlib recently. Python would not close by pressing ctrl-c when a graph was showed (issue #56 ). The problem has been solved, but now, when we close the graph manually, python is still running. It must be shutdown by pressing ctrl-c absolutely. There must be to do both.

We want to reach 90% coverage for this file.
Check coverage with coverage run -m unittest then coverage html and coverage_report_html/index.html

We want to reach 90% coverage for these file.
Check coverage with coverage run -m unittest then coverage html and coverage_report_html/index.html

We want to reach 90% coverage for this file.
Check coverage with coverage run -m unittest then coverage html and coverage_report_html/index.html

On macOS and probably Windows, if a python script displays() a trace, then Ctrl-C will not quit the program. One must close the window. This is very annoying but it is not a problem specific to RayTracing, it is a problem related to matplotlib. Many hacks exist on the web to solve that problem, but I have not found one that is robust and working well (you can google matplotlib ctrl-c).

I want Ctrl-C to work, but I want I solution that works on all platforms.

We want to reach 90% coverage for this file.
Check coverage with coverage run -m unittest then coverage html and coverage_report_html/index.html

Move to Sphynx and sphynx-style documentation because the current format looks like garbage.

1. This requires looking through the different formats for Python documentation here: https://realpython.com/documenting-python-code/ and here: https://www.sphinx-doc.org/en/master/
2. Using a simple test file such as rays.py, see what the output format looks like once it is formatted properly.
3. Modify all source files to adopt the documentation format
4. Create scripts to fully document and update when needed.

It is not easy to put several labels on a graph without any overlap. A solution should be found.

There is a calculation that turns out with A == 0 and then a division by zero crashes. I am forgetting where it is and I have no test to illustrate it.

We will show the code (or small excerpts) for various problems. I need code for:

Intensity through confocal detection through pinhole for different pinholes, like the problem set in BPH-Imaging class.

They should, because they have a non-null thickness (Matrix explicitly say so).

The y-scale is not always set appropriately when the elements have infinite diameters: the rays will go beyond the element drawn on the figure. It should be simple to figure out a way to set the displayHalfHeight appropriately based on the highest ray.

Incorrect, see comments below
The warnings package now makes the tests stop if a warning was issued.
There is a file called env.py that is imported in all tests. There is a setting for the behaviour of warnings that can be set, and it should be added to env.py.

For instance, in the terminal, from the tests directory, running python -m unittest will stop at the first warning.

The drawing is just a line. It should be some sort of curved line with colours for indices. This may imply rewriting the drawing code of others to match indices and colours.

A method must be found to figure out what "the right size" should be for an arrow head, the font, the position of a label, the size of the "ticks" on the aperture. Right now, they are given in transData space (i.e. in actual distances corresponding to real thickness and distances) but for long ImagingPaths or MatrixGroups, they may be dwarfed by the scale of the system and look funny.

We need an intelligent way of showing very small objects.

Currently, the default when displaying a trace is to use a user-defined objectHeight and fanAngle with decent default values. This is probably not that useful. We should default to principal and axial rays when they exist and use a unity object height otherwise. Probably.

It would be nice and useful to have a function, in some sort of PlotManager, that would take code as an argument, run it, and print the code on screen with syntax highlighting. We could even have have the option of providing the code as a string or as a file on disk. This way, for instance, we could store all examples in the examples directory and access them directly.

CurvedMirror and ThickLens do not override flipOrientation. This is a problem, because in the case of:

1. CurvedMirror:

• R should become -R. This changes the C component of the ABCD matrix.

2. ThickLens:

• R1 sould become -R2 (and vice versa). This changes the A and D components.

Labelling focal points with appropriate secondary labels should be possible, maybe a superscript?

It would be useful to have dotted rays originating from a virtual image.

Gather all projects in a directory and make templates for common IDEs.

Warnings are only printed with the classic print method. When we use the warnings package (builtin package) it prints in red font and warnings are easier to see in console. It also allows for some sort of tracking: it is possible to test if warnings are really sent to the user, it is possible to convert them to errors, etc.

More info here.

If you look up the PyPi raytracing page, the figures don't show up. I think the links to the images in the main README.md should be absolute URL, and point directly to the master branch on GitHub.

It should allow one to remove the display of element labels.

We want to reach 90% coverage for this file.
Check coverage with coverage run -m unittest then coverage html and coverage_report_html/index.html

Currently, they are almost the same but options may be missing.

Right now, we only check if other is None. We should check if it is not an instance of Ray, otherwise we get AttributeError because the other type doesn't have a property called y (or theta).

They respectively return a ImagingPath instance and a LaserPath instance, but those classes are in other files not imported. It is also worth mentioning that they both inherit from MatrixGroup, so it is kind of incoherent to use them in MatrixGroup.

Question:
Are those methods really necessary in MatrixGroup?

• Yes: We have to find a way to import them without having a circular import problem.
• No: We should remove them.

We want to reach 100% coverage for this critical file.
Check coverage with coverage run -m unittest then coverage html and coverage_report_html/index.html

PyCharm creates a folder called: .idea/ : what do we do with this? Should this be on GitHub or be removed? There are always conflicts when more than one person uses the project. Should we find user files and remove them from repo?

We want to reach 90% coverage for this file.
Check coverage with coverage run -m unittest then coverage html and coverage_report_html/index.html

RayTracing requires tkinter

If you are not installing Python with Anaconda, it is important to keep tcl/tk support during python install since it is required by matplotlib's backend (tkinter). This is no problem if you follow default installation options.

Version compatibility

I tested RayTracing and it currently works on Python 3.6 and newer versions (3.7 & 3.8).

Since Python 3.5 is still an active Python 3 release, I tried to install RayTracing, but it fails to run because of a new type hint syntax for variable annotations (PEP 526) used in imagingpath.py:

thetaUp = (stopDiameter / 2.0 - A * y) / B  # type: float
thetaDown = (-stopDiameter / 2.0 - A * y) / B  # type: float

Conclusion

• We need to choose if we want to discard PEP 526 to support Python 3.5+ or keep it and 'only' support 3.6+.
• README.md needs to be updated to tell the required python version.

Because we mostly use Anaconda, we are not explicitly stating the dependencies in setup.py. We need to go through the list of dependent modules if one does not use anaconda.

To find the entrance pupil, we first check if the aperture has a finite diameter. If not, we simply return (None, None), otherwise we find the aperture stop and the transfer matrix to the aperture stop. With this transfer matrix, we find the associated backward conjugate. In some cases, the transfer matrix has A == 0 and the backward conjugate gives (None, None). Then, we try to get the magnification of None and this raises an AttributeError. If an exception as to be thrown, we should at least give a better message, because AttributeError gives 'NoneType' object has no attribute 'magnification' which doesn't really describe the problem of an absence of backward conjugate. We can also return (None, None) like other methods do.

I like using http://www.webgraphviz.com to visualize hierarchies. I made a graph in __init__ but it must be updated manually. It would be nice to have the relevant class hierarchy automatically with a script. There must be something somewhere that does that. We could put the code in docs/ or examples/ not sure where. This would be for developers but maybe also users.

digraph G {
   rankdir="LR";

    subgraph elements {
        "Matrix" -> "Space"
        "Matrix" -> "Lens"
        "Matrix" -> "Aperture"
        "Matrix" -> "ThickLens"
        "Matrix" -> "CurvedMirror"
        "Matrix" -> DielectricInterface
        "Matrix" -> "MatrixGroup"
        "ThickLens" -> "DielectricSlab"

        "MatrixGroup" -> "AchromaticDoubletLens"
        "AchromaticDoubletLens" -> "thorlabs.part#"
        "AchromaticDoubletLens" -> "eo.part#"
        "MatrixGroup" -> "Objective"
        "Objective" -> "olympus.part#"
    }
}

If this can be done in straight Python, perfect. Avoid using other packages if possible.
I want an output like the one above for webgraphviz.

When we create a MatrixGroup with no element, largestDiameter() raises an IndexError exception because we try to access the first element of an empty list. I think this should be handled in a better way.

Question:
Should we keep it like that?

• Yes: Ok.
• No: Should we throw another type of exception, more specific with a proper message? Or should we just return None (or another thing)?

When I was writing a test for traceManyThroughInParallel, I realized that the method returned Rays of Rays (of Ray). It is not coherent with the non parallel method, which returns Rays of Ray. I think it has something to do with the way we map traceManyThrough with the list of Ray and the way we return the results from the mapping.

When we try to get a specific element of a Rays object, it throws an exception because we can't index it. It should be possible to do it. A user can be interested in getting a specific Ray form Rays.

The documentation is currently based on simple docstrings. We need better by looking at Sphynx and other options. Ideally, the format will automatically produce a nice looking HTML or Markdown output.

@elahe: Looking at documentation requirements:

1. what information do we need to provide to users? (function description, examples, tutorials, etc...)
2. what is the best format to provide this information? (web site, online help, etc...)
3. what are possible methods to do 1) and 2) ?

It may be interesting to look at https://readthedocs.org

As much as possible, Matrix and other optical elements, ImagingPath and others should not be involved in layout details. Currently, for simplicity, elements "draw themselves" and MatrixGroups "display themselves". This is poor design.

We should be able to create a central class LayoutHelper that manages the layout (screen, paper, etc) and probably offers a simplified view of matplotlib drawing commands.

We have several important references, and we will need to have comments at the end, with general recommendations depending on the level of the reader.

1. Gerhard Kloos ""Matrix Methods for Optical Layout" (excellent book fairly easy)
2. Greivenkamp "Field guide to Geometrical optics" (very compact, harder)
3. Rongguang Liand "Optical Design for Biomedical Imaging" (haven't read)
4. Smith "Modern Optical Design" (the ultimate reference for experts)
5. Pedrotti "" Very pedagogical, one of my favourite.
6. Hecht "Optics", a bit dated, no phaser notation
7. Saleh and Tech "Fundamentals of Photonics" great book all around but nothing about optical design and stops.

References available at: https://paperpile.com/shared/ntJWWw

Greivenkamp, John E. 2004. Field Guide to Geometrical Optics. Vol. 1. SPIE press Bellingham, WA.
Kloos, Gerhard. 2007. Matrix Methods for Optical Layout. SPIE Press.
Mahajan, Virendra N. 1991. Aberration Theory Made Simple. SPIE Press.
Pedrotti, Frank L., Leno M. Pedrotti, and Leno S. Pedrotti. 2017. Introduction to Optics. Cambridge University Press.
Saleh, Bahaa E. A., and Malvin Carl Teich. 2019. Fundamentals of Photonics. John Wiley & Sons.
Smith, Warren J. 2008. Modern Optical Engineering. Tata McGraw-Hill Education.

Those interested in writing need to meet with me to make a quick outline and split the work of writing some of those sections.

I would like to have a mode where an element is drawn with its principal planes, nodal planes, focal planes, etc...

Method flipOrientation from Matrix doesn't flip properly. When writing a test case, I realized that vertices and indices were not switched between front and back. It is a simple correction that needs to be done.

Best places to start: Matrix, then MatrixGroup, OpticalPath, then ImagingPath

Read the procedure for writing tests on https://github.com/DCC-Lab/RayTracing/wiki/HOWTO-write-Unit-Tests.

Unit tests are very limited at this point. To create more tests, do to the tests directory and create a file with a name starting with testsWhatever.py. Look at other files for examples.
To run, simply use: python -m unittest testsWhatever.py.
To run with coverage, use: coverage run -m unittest discover, then coverage html and look at coverage_html_report/index.html.