Merge pull request #9 from drombas/doc_api

DOC: add detailed API

doc/functions.rst

@@ -7,7 +7,6 @@ These are all the functions implemented in RETIMAT
 
 File reading
 ============
-.. automodule:: io
 
 .. autofunction:: io.read_vol
 
@@ -33,6 +32,107 @@ File reading
 
 ----
 
+
+Visualization
+=============
+
+.. autofunction:: visu.generate_report
+
+----
+
+.. autofunction:: visu.plot_sectors
+
+----
+
+.. autofunction:: visu.spider_plot
+
+----
+
+
+Reflectance
+===========
+
+.. autofunction:: reflectance.compute_attenuation
+
+----
+
+.. autofunction:: reflectance.image_quality
+
+----
+
+.. autofunction:: reflectance.normalize_reflectance
+
+----
+
+.. autofunction:: reflectance.reflectance_map
+
+----
+
+.. autofunction:: reflectance.stack_bscans
+
+----
+
+Structural analysis
+===================
+
+.. autofunction:: structure.compute_thickness
+
+----
+
+.. autofunction:: structure.fit_pit_model
+
+----
+
+.. autofunction:: structure.get_morph_params
+
+----
+
+.. autofunction:: structure.smooth_pit
+
+----
+
 Spatial analysis
 ================
 
+.. autofunction:: spatial.find_fovea
+
+----
+
+.. autofunction:: spatial.flip_coordinates
+
+----
+
+.. autofunction:: spatial.get_ascan_coordinates
+
+----
+
+.. autofunction:: spatial.resample_map
+
+----
+
+.. autofunction:: spatial.sectorize_map
+
+----
+
+.. autofunction:: spatial.sectorize_peripapillar
+
+----
+
+Texture analysis
+================
+
+.. autofunction:: texture.fractal_dimension
+
+----
+
+.. autofunction:: texture.GLCM_features
+
+----
+
+.. autofunction:: texture.lacunarity
+
+----
+
+.. autofunction:: texture.LBP_features
+
+

src/io/read_bin.m

@@ -22,9 +22,9 @@
 %
 % Example
 % -------      
-% Read fda file
+% .. code-block:: matlab
 %
-%   I = read_bin(file.bin)
+%   I = read_bin('myfile.bin')
 
 if nargin==1
    im_size = [664 512];

src/io/read_e2e.m

@@ -48,13 +48,16 @@
 % --------      
 % Read all the information in a .e2e/.E2E file
 % ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-%     file = 'my_oct.e2e';
-%     [header, segment, bscan, fundus] = read_e2e(file)
-%     
+% .. code-block:: matlab
 %
+%    file = 'my_oct.e2e';
+%    [header, segment, bscan, fundus] = read_e2e(file)
+%     
 % Read only the header of the .e2e/.E2E file (faster)
 % ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-%     file = 'my_oct.e2e';
+% .. code-block:: matlab
+%
+%    file = 'my_oct.e2e';
 %     header = read_e2e(file)
 
 verbose   = any(strcmp('verbose', varargin));

src/io/read_fda.m

@@ -9,8 +9,7 @@
 % * **varargin**:    Optional flags from the list:
 %
 %   - 'verbose': If provided, reading info is displayed.
-%   - 'get_coordinates': If provided A-scan coordinates are returned. This only works if the scanning pattern is
-%                    horizontal raster (pending to implement others).
+%   - 'get_coordinates': If provided A-scan coordinates are returned. 
 %
 %
 % Output arguments
@@ -35,6 +34,9 @@
 % 1. Identify data chunks present in file (not all are always present)
 % 2. Read specific chunks with the relevant information
 %
+% 'get_coordinates' flag only works if the scanning pattern is horizontal
+% raster (pending to implement others).
+%
 %
 % References
 % ----------
@@ -44,10 +46,10 @@
 % [2] OCT-Converter: https://github.com/marksgraham/OCT-Converter
 %
 %
-% Examples
-% --------      
-% Read fda file
-% ^^^^^^^^^^^^^
+% Example
+% -------      
+% .. code-block:: matlab
+%
 %   [header, segment, bscan, fundus] = read_fda(file)
 
 verbose         = any(strcmp('verbose', varargin));

src/io/read_img.m

@@ -48,7 +48,7 @@
 %
 % Example 
 % -------      
-% Read img file
+% .. code-block:: matlab
 %
 %   [header, bscan] = read_img('myfile.img')    
 

src/io/read_vol.m

@@ -53,10 +53,14 @@
 % --------      
 % Read all the information in a .vol file
 % ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-%     [header, segment, bscan, fundus] = read_vol('my_oct.vol')
+% .. code-block:: matlab
+%
+%    [header, segment, bscan, fundus] = read_vol('my_oct.vol')
 %     
 % Read only the header of the .vol file (faster)
 % ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+% .. code-block:: matlab
+%
 %     header = read_vol('my_oct.vol')
 
 visu            = any(strcmp('visu', varargin));

src/io/read_xml_iowa.m

@@ -59,7 +59,7 @@
 %
 % Example
 % -------      
-% Extract data from iowa xml segmentation
+% .. code-block:: matlab
 %
 %   [header, seg] = read_xml_iowa('my_file_Surfaces_Iowa.xml')
 

src/reflectance/compute_attenuation.m

@@ -1,72 +1,63 @@
 function att = compute_attenuation(bscan, scale_z, method, seg)
-%COMPUTE_ATTENUATION Compute voxelwise attenuation coefficient.
+% Compute voxelwise attenuation coefficient based on [1] or [3].
 %
-%   att = compute_attenuation(bscan, header)
-%   Compute voxelwise depth-resolved attenuation based on [1] or [3].
+% Input arguments
+% --------------- 
+% * **bscan**:       matrix with B-scans of dimensions n_axial x n_ascan x n_bscan. If 2D matrix it will be interpreted as a single B-scan.
 %
-%   Input arguments:
-%  
-%   'bscan'          Matrix with B-scans of dimensions n_axial x n_ascan x 
-%                    n_bscan. If 2D matrix it will be interpreted as a
-%                    single B-scan.
+% * **scale_z**:     axial (depth) resolution in mm.
 %
-%   'scale_z'        Axial resolution in mm.
+% * **method**:      method used to compute the attenuation coefficient.
 %
-%   'method'         Method used to compute the attenuation coefficient.
-%                    Options: 'vermeer_2014', 'vanderschoot_2012'
-%                    Default: 'vermeer_2014'
+%   - 'vermeer_2014' (default)
+%   - 'vanderschoot_2012'
 %
-%   'seg'            Struct with segmentation data used with the
-%                    'vanderschoot_2012' method [3]
+% * **seg**:         struct with segmentation data used with the 'vanderschoot_2012' method [3]
 %  
 %
-%   Output arguments:
-%  
-%   'att'            Attenuation coefficient per voxel.          
+% Output arguments
+% ---------------- 
+% * **att**:         attenuation coefficient per voxel.          
 %  
 %   
-%   Notes
-%   -----
-%   The precise measurement of tissue attenuation coefficient is difficult
-%   and still a research topic. This function provides an approximate
-%   value based on assumptions on optical tissue properties [1]. You may
-%   want to read [2] to check how this method compares to others.
-%
-%   The method in [3] is currently only supported for RNFL and returns a
-%   total attenuation value for each a-scan instead of a 3D matrix.
-%
-%   For the methods to work it is important to use raw voxel intensity. For
-%   instance reading .vol files with the 'raw_pixel' flag.
-%
-%
-%   References
-%   ----------
-%   [1] Vermeer, Depth-resolved model-based reconstruction of attenuation 
-%   coefficients in optical coherence tomography, Biomedical Optics Express
-%   2014, https://doi.org/10.1364/BOE.5.000322 
-%
-%   [2] Chang, Review of methods and applications of attenuation 
-%   coefficient measurements with optical coherence tomography, Journal of
-%   Biomedical Optics, 2019, https://doi.org/10.1117/1.JBO.24.9.090901
-%
-%   [3] van der Schoot, The Effect of Glaucoma on the Optical Attenuation
-%   Coefficient of the Retinal Nerve Fiber Layer in Spectral Domain Optical
-%   Coherence Tomography Images, IOVS, 2012, 
-%   https://doi.org/10.1167/iovs.11-8436
+% Notes
+% -----
+% The precise measurement of tissue attenuation coefficient is difficult and
+% and still a research topic. This function provides an approximate value
+% based on assumptions on optical tissue properties [1]. You may want to
+% read [2] to check how this method compares to others.
+%
+% The method in [3] is currently only supported for RNFL and returns a
+% total attenuation value for each a-scan instead of a 3D matrix.
+%
+% For the methods to work it is important to use raw voxel intensity. For
+% instance reading .vol files with the 'raw_pixel' flag.
+%
+%
+% References
+% ----------
+% [1] Vermeer, Depth-resolved model-based reconstruction of attenuation 
+% coefficients in optical coherence tomography, Biomedical Optics Express
+% 2014, https://doi.org/10.1364/BOE.5.000322 
+%
+% [2] Chang, Review of methods and applications of attenuation 
+% coefficient measurements with optical coherence tomography, Journal of
+% Biomedical Optics, 2019, https://doi.org/10.1117/1.JBO.24.9.090901
+%
+% [3] van der Schoot, The Effect of Glaucoma on the Optical Attenuation
+% Coefficient of the Retinal Nerve Fiber Layer in Spectral Domain Optical
+% Coherence Tomography Images, IOVS, 2012, 
+% https://doi.org/10.1167/iovs.11-8436
 %   
 %
-%
-%   Example
-%   ---------      
-%   % Load a .vol file and compute the attenuation coefficient
+% Example
+% -------      
+% Load a .vol file and compute the attenuation coefficient
+% ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+% .. code-block:: matlab
 %
 %     [header,~,bscan] = read_vol('my_file.vol','raw_pixel');
 %     att = compute_attenuation(bscan, header.scale_z);
-%
-%
-%  
-%   David Romero-Bascones, [email protected]
-%   Biomedical Engineering Department, Mondragon Unibertsitatea, 2022
 
 if nargin == 2
     method = 'vermeer_2014';