ODF actor implemented with Ray Tracing (#869)

* added file for experimentation

* added SH implementation with 2 parameters

* adjusted script

* added coefficients to experimental implementation

* deleted unused variables

* added files for experimentation on each issue

* added file for experimentation with textures

* updated files

* passing coefficients through texture with few glyphs

* comparison of passing coefficients with uniforms vs texture

* Pruning duplicate coeffs.

* Refactoring FS declaration code.

* Added temp call to Fury's Central Differences Normals calculation.

* Added new file with changes.

* Restored texture_coefficients.py

* organized files

* adjusted uv vals

* Added minor changes.

* added new file for SH efficient implementation

* Minor changes in shader code.

* Added first version of Peters' paper.

* Added difinitions for constants.

* Added first functions of main shaders.

* All functions added.

* clear

* Removed rotation code and resolution dependent code.

* Renamed folder spherical_harmonics as rt_odfs.

* Organized main code.

* Created ray_traced_3.py to simplify ray_traced_1.py content. Removed BRDF functions.

* added SH efficient implementation to the base impl with texture

* Added minor changes to base Ray Tracing implementation (ray_traced_1.py).

* Minor changes on ray_traced_3.py.

* Minor changes in ray_traced_1.py

* Forwarded camera right and up vectors.

* Used 3D point as frag_coord for uv mapping.

* Tournier first implementation

* updated files

* added Tournier impl

* Improved description of ray_traced_3.py

* Prep for new ray_traced file.

* Minor changes to ray_traced3.py

* Created ray_traced_6.py to fix scalability.

* Minor changes to ray_traced_6.py

* Added README and renamed ray_traced files.

* Added ray_traced_4.0.py as an analogous version of ray_traced_2.0.py. Updated README.

* Removed ray_traced_6.0.py from PR.

* implementation with a slice

* made adjustments on odf slice example

* updated README

* Removed unused black tags.

* Minor changes in several ray_traced experiments.

* Improved multiplatform compatibility of ray_traced_6.0.py. Changed illumination model.

* fixed scaling

* Fixed merge.

* added odf actor implementation

* adjusted scaling

* Added ray_traced_7.0.py which includes an argument parser.

* Added DIPY's ODF slicer python script with argument parser for profiling tool.

* Minor changes to ray_traced_7.0.py

* Renamed experimental folder.

* Changed basis to Tournier's.

* reorganized files

* Added folders for Descoteaux and Tournier basis.

* Updated ray_traced scripts to use spherical harmonics basis.

* Added ray_traced_6.5.py to debug performance issues.

* added degree param

* adjusted the degree setting

* Changed first uniform.

* Added ray_traced_3.5.py to take single ODF screenshot.

* added tests

* adjustments on tests and parameter validation

* Added Min-Max Normalization function.

* Added composed eval sh.

* Moved newton_bisection.frag to root_finding folder.

* reorganized and refactored odf actor

* Re-added newton_bisection.frag to rt_odfs.

* Fixed uniform and flats data type. Added numCoeffs param to rayGlyphInteresctions function.

* Moved dipy_slicer.py script to personal repo. Renamed as odf_slicer_cli.py

* Minor fix on uncertainty cone actor.

* Replaced SH_DEGREE with shDegree in rayGlyphIntersections function.

* Added extra arguments to rayGlyphIntersections function.

* Renamed variables in rayGlyphIntersections finction.

* Added new eval_sh.frag.

* Added dynamic evalSH function.

* Refactored eval_sh_x functions.

* Refactored getInvVandermonde function.

* Removed unnecessary eval_sh.frag file.

* added odf actor implementation

* adjusted scaling

* reorganized files

* added degree param

* adjusted the degree setting

* added tests

* adjustments on tests and parameter validation

* reorganized and refactored odf actor

* added odf actor implementation

* adjusted scaling

* reorganized files

* added degree param

* adjusted the degree setting

* added tests

* adjustments on tests and parameter validation

* reorganized and refactored odf actor

* added odf actor implementation

* adjusted scaling

* reorganized files

* added degree param

* adjusted the degree setting

* added tests

* adjustments on tests and parameter validation

* reorganized and refactored odf actor

* adjusted odf actor and added example

* adjustments on variables name and handle degree with uniform

* made suggested changes

* adjusted odf actor test

* fixed format

* made adjustments to the format

* fixed format

* fixed codespell and docs ci's

---------

Co-authored-by: Javier Guaje <[email protected]>

.codespellrc

@@ -2,4 +2,4 @@
 skip = .git,*.pdf,*.svg,*.bib,*.html
 # ue,lod,ans,lastr,numer,lamda,PrIs -- variable names
 # Hart,Flagg -- name
-ignore-words-list = IST,nd,te,ue,lod,hart,ans,lastr,numer,lamda,flagg,pris,lod,IST,tese
+ignore-words-list = IST,nd,te,ue,lod,hart,ans,lastr,numer,lamda,flagg,pris,lod,IST,tese,shs

fury/actor.py

@@ -7,6 +7,7 @@
 import numpy as np
 
 from fury import layout as lyt
+from fury.actors.odf import sh_odf
 from fury.actors.odf_slicer import OdfSlicerActor
 from fury.actors.peak import PeakActor
 from fury.actors.tensor import (
@@ -4019,3 +4020,67 @@ def uncertainty_cone(
     angles = main_dir_uncertainty(evals, evecs, signal, sigma, b_matrix)
 
     return double_cone(centers, evecs, angles, colors, scales, opacity)
+
+
+def odf(centers, coeffs, sh_basis="descoteaux", scales=1.0, opacity=1.0):
+    """
+    FURY actor for visualizing Orientation Distribution Functions (ODFs) given
+    an array of Spherical Harmonics (SH) coefficients.
+
+    Parameters
+    ----------
+    centers : ndarray(N, 3)
+        ODFs positions.
+    coeffs : (N, M) or (N, 6) or (N, 15) or (N, 28) or (N, 45) or (N, 66) or
+        (N, 91) ndarray.
+        Corresponding SH coefficients for the ODFs.
+    sh_basis: str, optional
+        Type of basis (descoteaux, tournier)
+        'descoteaux' for the default ``descoteaux07`` DIPY basis.
+        'tournier' for the default ``tournier07`` DIPY basis.
+    scales : float or ndarray (N, ), optional
+        ODFs size.
+    opacity : float, optional
+        Takes values from 0 (fully transparent) to 1 (opaque).
+
+    Returns
+    -------
+    odf: Actor
+
+    """
+
+    if not isinstance(centers, np.ndarray):
+        centers = np.array(centers)
+    if centers.ndim == 1:
+        centers = np.array([centers])
+
+    if not isinstance(coeffs, np.ndarray):
+        coeffs = np.array(coeffs)
+    if coeffs.ndim != 2:
+        if coeffs.ndim == 1:
+            coeffs = np.array([coeffs])
+        else:
+            raise ValueError("coeffs should be a 2D array.")
+    if coeffs.shape[0] != centers.shape[0]:
+        raise ValueError(
+            "number of odf glyphs defined does not match with number of centers"
+        )
+
+    coeffs_given = coeffs.shape[-1]
+    degree = int((np.sqrt(8 * coeffs_given + 1) - 3) / 2)
+    if degree % 2 != 0:
+        degree -= 1
+    coeffs = coeffs[:, : int(((degree + 1) * (degree + 2)) / 2)]
+    if not isinstance(scales, np.ndarray):
+        scales = np.array(scales)
+    if scales.size == 1:
+        scales = np.repeat(scales, centers.shape[0])
+    elif scales.size != centers.shape[0]:
+        scales = np.concatenate(
+            (scales, np.ones(centers.shape[0] - scales.shape[0])), axis=None
+        )
+
+    total = np.sum(abs(coeffs), axis=1)
+    coeffs = np.dot(np.diag(1 / total * scales), coeffs) * 1.7
+
+    return sh_odf(centers, coeffs, degree, sh_basis, scales, opacity)