% WASL
% version 10.6.1
% a MATLAB-based toolbox for speech science
% By Steven M. Lulich
%
% Introduction and boring stuff
% WASL is a MATLAB-based toolbox for speech science. More specifically, WASL is designed around the visualization and analysis of speech-related biomedical imaging data, with some support for integrating acoustic signals and other data modalities (e.g. digitized palate impressions). Even more specifically, WASL is primarily focused on using 3D/4D ultrasound and 3D structural MRI data. The architecture of WASL is designed to allow for relatively easy extensibility through the use of "plugins". There have been many versions of WASL over the years, and this documentation is specific to version 10.6.1. For the most part, WASL has been fairly stable since version 3.6, and so much of this documentation will be easily applicable to versions between 3.6 and 10.6.1; similarly, it is expected that this documentation will be easily applicable to versions higher than 10.6.1.
% This documentation assumes the following version of MATLAB:
% MATLAB Version: 23.2.0.2515942 (R2023b) Update 7
% WASL has been in development for more than a decade, and it should be fully-backward compatible with previous versions of MATLAB within that time frame. More recent or future versions of MATLAB may be incompatible with WASL.
%
% Chapter 1: How to install and run WASL.
% You can download the toolbox from the website of the Speech Production Laboratory at Indiana University: https://spliu.synology.me/software/software.html
% Simply double-click on the downloaded toolbox to install it through MATLAB.
%
% After installing WASL, you can find out where the files live on your computer by running the following code:

which('WASL')

% If you have previously installed WASL (the same or a different version), you can see the location of each installation by running the following code instead:

which('WASL','-ALL')

% It is useful to know where the WASL toolbox was installed so that you can access the files directly whenever desired. For example, you may want to study the code to know exactly what WASL is doing "under the hood"; or you may want to edit some of the code; or you may want to create your own new plugin.
%
% By installing WASL as a toolbox, it is automatically in the MATLAB path. To run WASL from the MATLAB command window, simply uncomment and run the following code in the command window:

% WASL

% Note that you should avoid running WASL directly from this LiveScript because it will cause the LiveScript itself to become a very large file.
%
% You can find out which version of WASL you are running in two ways. First, you can inspect the WASL.m code:

edit WASL.m

% Line 15 specifies the 'Name' of the WASL window as 'WASL 10.6.1' (or whatever version you are using).
% Second, you can simply look at the top-left corner of the WASL window, where the WASL version is clearly displayed (by executing line 15 in WASL.m).
%
% Chapter 2: How to load a 3D/4D ultrasound (*.DCM) file
% You might not want to immediately start working with 3D/4D ultrasound data (henceforth referred to as "a DCM file"), but starting with 3D/4D ultrasound will allow us to get a feel for much of WASL's funcationality, which you can then apply to other forms of data.
% There are two ways to load a DCM file into WASL: the GUI and the command line. Before illustrating both of these methods, let's talk a bit about what is going on "under the hood".
% WASL is tailored for use with 3D/4D ultrasound files produced by a Philips EPIQ 7G ultrasound machine with a Philips x6-1 digital 3D/4D transducer. For detailed information about this particular machine and how it relates to other ultrasound machines, see https://doi.org/10.1016/j.wocn.2018.10.001 and https://doi.org/10.1044/2019_PERS-SIG19-2019-0001. Other types of ultrasound files (e.g. 2D, xPlane, etc.) as well as data produced by other ultrasound machines could in principle be compatible with WASL. My recommendation would be to create a copy of the +DCM plugin, name it something quasi-useful (it must be a '+' followed by three letters), and then edit it to be able to read in the new data files. [Yes, it would be good to modularize the code a bit more. Some day... Or feel free to do it yourself!]
% WASL deals with DCM files through the +DCM plugin. Every plugin is named in the same way, with a '+' followed by three letters. The '+' designates the plugin as a MATLAB namespace and allows functions within the plugin to be called using dot notation (see https://www.mathworks.com/help/matlab/matlab_oop/namespaces.html#mw_7401e392-018c-4253-a1c3-50b02cd3bd14 for MATLAB documenation about namespaces).
% The key function for loading the data from a DCM file is:
%             plugins.DCM.loadPhilipsDCM.m
% You can use this function directly (circumventing the WASL GUI entirely) in the following way:

[filename, pathname] = uigetfile('*.dcm', 'Select a 3D/4D ultrasound file...');
output = plugins.DCM.loadPhilipsDCM(pathname,filename);
V = output{1};
C = output{2};
scale = output{3};

% The variable V contains the 4-dimensional array of ultrasound image intensity values, C is equal to size(V), and scale contains the size in cm of a voxel in each of the three spatial dimensions (scale(1:3)) as well as the frame rate in fps in the temporal dimension (scale(4)). Note that in this example, the DCM file does not load or display the DCM file in the WASL GUI, nor does it even open a WASL GUI to begin with.
%
% The two ways to load a DCM file into WASL are as follows:
% In the GUI, select the "DCM" tab and then click the "Load new DCM or FLD file..." button. Navigate to where your DCM file is, and select it. Most 3D/4D ultrasound DCM files are quite large, so it may take up to 10 seconds or more for the file to load and the data to appear in the GUI as a set of three images.
% Once the DCM file is loaded into WASL, you can pull the V, C, and scale data directly from the WASL figure by running the following code from the command line:

WASLx = get(findobj('Name','WASL 10.6.5'));
V = WASLx.UserData.tongue.V;
C = WASLx.UserData.tongue.scaling.C;
scale = WASLx.UserData.tongue.scaling.scale;

% Alternatively, you can direct WASL to open a particular DCM file directly from the command line, and then you can pull out the V, C, and scale data in the same way as above. The best way to do this is to save the WASL figure in a handle variable when you launch it:

WASLx = WASL;
[filename, pathname] = uigetfile('*.dcm', 'Select a 3D/4D ultrasound file...');
output = plugins.DCM.loadnewFLD(WASLx,pathname,filename);
V = output{1};
scaling = output{2};
C = scaling.C;
scale = scaling.scale;

% Note that in this last example, WASL was used to load the DCM file, but it does not load and display the DCM file in the WASL GUI.
% Another alternative is to use the DCMreader4D function, which in turn calls the plugins.DCM.loadPhilipsDCM function:

[V,C,scale] = DCMreader4D; % If you want to select a file with the uigetfile user interface

% or...

[V,C,scale] = DCMreader4D(pathname, filename); % If you already know the path and file name

%
%