Planning for Version 1.x

[CnlPepper]

Raysect's major version is currently sitting on V0.x due to the core API and architecture remaining relatively stable. The current architecture has worked well, however we have identified some areas where the core architecture has limited our ability to cleanly supply features our users desire. For example, access to additional location metadata specific to primitives. To provide access to this data requires a significant change to the optical material surface evaluation methods and modification of all materials. In addition we now wish to prepare the core to support polarisation and scattering.

This issue will be used to collect a list of proposed API changes and additional core features for raysect's V1 architecture. Once the list is assembled, separate V1 issues will be created to address the implementation of specific changes.

[CnlPepper]

Proposed raysect.optical changes:

1. Pass Intersection object to all relevant material evaluation methods rather than unpacking.

This will allow future expansion of the attributes passed to the materials without changing the material API. It would also permit primitives to supply their own sub-classes of Intersection that include additional meta data. For example meshes can additionally return triangle ID and barycentric coordinates for mesh intersection. This has been a commonly requested feature.

Adding UV texture coordinates (texture support) will then require no API changes.

2. Rename Spectrum to UnpolarisedSpectrum, add a new based class Spectrum and prepare for the addition of PolarisedSpectrum. Update Ray to include a polarised toggle.

The Ray will internally hold an integrator attribute that is populated with an unpolarised or polarised integrator depending on configuration. Depending on the integrator used, either an UnpolarisedSpectrum or a PolarisedSpectrum object will be returned.

If this approach proves awkward to handle via cython (due to type inference), the Ray will be split into unpolarised.Ray and polarised.Ray with corresponding Spectrum objects. This may be cleaner but will require user code refactoring.

3. Rework all materials to provide calculation paths for polarised, unpolarised and volume scattering.

The current material evaluation methods will be renamed to evaluate_surface_unpolarised and evaluate_volume_unpolarised.

Methods evaluate_surface_polarised and evaluate_volume_polarised will be added to support polarised rays.

Methods evaluate_scatter_unpolarised and evaluate_scatter_polarised will be added to support physics than can be modelled as volume scattering effects (e.g. mie scattering, gradients of refractive index and gravitational lensing). Volume scatting will allow the ray to be refired at any point along the original ray path and permit the spectrum to be altered.

4. Update observers to understand ray orientation of polarised light.

Polarised rays have an orientation (e.g. electric field aligned with y-axis in local space) the observer API may need to be altered to support it's configuration.

5. Volume exclusivity levels.

At present all the volumes a ray segment resides in are evaluated and their results combined (one after the other). This poses an issue for many use cases where one volume should be exclusive. For example a glass sphere present inside a box of scattering material. At present the user would have to cut a spherical volume out of the box to prevent the scattering volume being evaluated in the sphere. To make life easier for users, materials will gain an exclusivity level attribute. If a ray sits inside a collection of volumes and one of more materials define an exclusivity level, the material with the highest exclusivity level will be evaluated. If two or more volumes share an exclusivity level, an exception will be raised. By default, all materials will be set to exclusive. Overlapping volume emitters will need to have exclusivity explicitly disabled (this will need to be the case for the downstream project Cherab and its plasma emitters).

[CnlPepper]

Created a new v1/development branch: 8be63a5e4e06e38850b739872187359ed16f530c.

All feature/bug fix branches targetting v1 should be prefixed with v1/ e.g v1/feature/polarisation.

[CnlPepper]

It has been decided that v1 will only support polarised light and reuse the existing class names. This will simplify the package for both users and developers.