plotBrain.m

function [p,boundary_plot,BOUNDARY] = ...
    plotBrain(vertices, faces, rois, varargin)
%PLOTBRAIN Wrapper for plotSurfaceROIBoundary
%   Syntax
%   ---
%   plotBrain(vertices, faces, rois, data)
%   plotBrain(surface, rois, data)
%   plotBrain(___, Name, Value)
%   [p,boundary_plot,new_cmap,BOUNDARY,new_climits,orig_data_climits] = plotBrain(___)
%   
%   
%   Description
%   ---
%   plotBrain(vertices, faces, rois, data) plots a surface patch object by
%   creating a surface mesh using `vertices` and `faces`, allocating each vertex
%   to a region using `rois`, and plotting each vertex or roi according to a
%   colormap.
%   plotBrain(surface, rois, data) uses the surface to generate the patch
%   object.
%   plotBrain(___, Name, Value) specifies additional parameters for plotting. 
%   [p,boundary_plot,new_cmap,BOUNDARY,new_climits,orig_data_climits] =
%   plotBrain(___) returns the objects generated by plotSurfaceRoiBoundary.
%   
%   
%   Examples
%   ---
%   figure; plotBrain(lh_verts, lh_faces, lh_aparc, 1:34);
%   figure; plotBrain(struct('vertices', rh_inflated_verts, 'faces', rh_faces), rh_HCPMMP1, 1:180, 'view', "rm", 'plotSurfaceROIBoundaryOptions', {'midpoint', autumn(10)});
%   
%   
%   Input Arguments
%   ---
%   vertices - vertex coordinates (matrix)
%   V × 3 matrix of xyz coordinates of surface vertices (V is the number of
%   vertices).
%
%   faces - face allocations (matrix)
%   F × 3 matrix, where each row is the vertex IDs that make up each face (F is
%   the number of faces).
%
%   rois - parcellation aka ROI allocation (vector)
%   V × 1 matrix, where each element is the ROI that each vertex is allocated
%   to.
%
%   data - data to be plotted (vector)
%   two options: data for each ROI: R × 1 matrix, where each element is the 
%                data for each ROI (where R is the number of ROIs); OR
%                data for each vertex: V × 1 matrix, where each element is the
%                data for each vertex.
%
%   surface - surface object containing vertices and faces (struct)
%   Struct with at least two fields, `vertices` and `faces`, as above.
%
%   Name-Value Arguments
%   ---
%   plotSurfaceROIBoundaryOptions - plotting options (cell)
%   Cell that contains arguments which are passed on to PLOTSURFACEROIBOUNDARY
%   without modification. In order, this should contain boundary_method, cmap,
%   colorUnknownGrey, linewidth, and climits.
%   
%   view - view perspective for current axis ("ll" (default)|"lm"|"rl"|"rm"|double)
%   Specifies the camera position to view the surface patch plot. Can be either
%   a two-letter string (specifying left/right hemisphere and medial/lateral
%   view), or a two- or three-element array specifying the line of sight.
%   
%   camlights - position of camlights ([80,-10;-80,-10] (default)|matrix)
%   If particularly desired, the position of the camlights can be specified
%   using an nCamlights × 2 matrix, where the two columns represent the x and y
%   coordinates of each camlight.
%   
%   
%   Output Arguments
%   ---
%   p, boundary_plot, new_cmap, BOUNDARY, new_climits, orig_data_climits
%   as described in PLOTSURFACEROIBOUNDARY
%   
%   
%   See also
%   ---
%   plotSurfaceRoiBoundary, VIEW
%   
%   
%   Authors
%   ---
%   Mehul Gajwani, Monash University, 2023

% TODO : add another wrapper for plotting 4 views in a line or grid (2 flags)
% TODO : add dependencies to MATLAB docstring

%% Prelims
ip = inputParser;
addRequired(ip, 'vertices');
addRequired(ip, 'faces');
addRequired(ip, 'rois');
addOptional(ip, 'data', false);

addParameter(ip, 'view', 'll'); % default view is left lateral
addParameter(ip, 'plotSurfaceROIBoundaryOptions', {'faces', parula(100), 0});
addParameter(ip, 'camlights', [[80, -10]; [-80, -10]]);
addParameter(ip, 'overrideAssertions', false);

parse(ip, vertices, faces, rois, varargin{:});


%% Re-allocate data if first argument is a struct
if ~ip.Results.data | isa(vertices, 'struct') %#ok<OR2> 
    data = reshape(ip.Results.rois, [], 1);
    rois = reshape(ip.Results.faces, [], 1);
    faces = ip.Results.vertices.faces;
    vertices = ip.Results.vertices.vertices;
else 
    data = reshape(ip.Results.data, [], 1);
    rois = reshape(ip.Results.rois, [], 1);
    faces = ip.Results.faces;
    vertices = ip.Results.vertices;
end


%% Assertions
if ~ip.Results.overrideAssertions
    assert(size(vertices, 1) == size(rois, 1), ...
        'vertices and rois are not the same length');
    assert(size(vertices, 2) == 3, ...
        'vertices needs x, y, z, coordinates');
    assert(max(faces(:)) == size(vertices, 1), ...
        'faces should use all the vertices');
    assert(size(faces, 2) == 3, ...
        'each face should have three vertices');
end


%% Do plotting
% use plotSurfaceROIBoundary
[p,boundary_plot,BOUNDARY] = ...
    plotSurfaceROIBoundary(...
    struct('vertices', vertices, 'faces', faces), rois, data, ...
    ip.Results.plotSurfaceROIBoundaryOptions{:});

% beautify axes
axis off; axis tight; axis equal;

% set camlights
camlights = ip.Results.camlights;
for ii = 1:size(camlights, 1)
    camlight(camlights(ii, 1), camlights(ii, 2));
end


%% Change view according to flag
if isa(ip.Results.view, 'double')
    view(ip.Results.view);
else
    switch ip.Results.view
        case "lm", view([90 0]);
        case "ll", view([-90 0]);
        case "rm", view([-90 0]);
        case "rl", view([90 0]);
        otherwise, view([0 90]); % top view
    end
end


end