This project started many years ago to standardize the way that I read in microscope data. This project has expanded to include many helpful functions and scripts when manipulating data from microscopes, namely high dimensional ones. Many modern microscopes are capable of capturing three-dimensional data with separate channels over time, or what I'll be calling 5-D data.
I hope that you find this repository as useful as I have. Please let me know if you have additions that you find useful that others will too.
These tools have been written with MATLAB's package paradigm.
This allows for a convenient grouping of similar functions.
This also keeps directories well organized.
There are two ways that you can make these packages available for MATLAB to use regardless of the current workspace directory.
One way (not recommended) is to just copy any directory with a + sign to your MATLAB folder in your user space.
For example, on windows this would be C:\Users\myuser\Documents\MATLAB
.
However, doing so will break the whole point of putting these functions in a git repository.
The recommend way is to add the packages to your MATLAB path.
This can be done with an addition to your startup.m file located in your user space.
root_programs.m
The root_programs.m
function is used to determine the root directory for MATLAB programs based on the operating system.
This function is crucial for defining a consistent starting point for package paths.
Create the Function:
root_programs.m
.root_programs
function code into this file.Function Usage:
userpath
.startup.m
The startup.m
script automatically runs each time MATLAB starts, setting up the environment, including adding necessary paths for your packages.
Create the Script:
startup.m
.Script Setup:
startup.m
script code into this file.pkgList
array to include the names of your MATLAB packages.Adding Package Paths:
root_programs
function to find the base directory.pkgList
.src/MATLAB
or src/matlab
subdirectories.Once you have set up the root_programs.m
function and the startup.m
script, MATLAB will automatically configure the paths to your packages each time it starts.
This setup simplifies the management of multiple MATLAB projects and packages, ensuring that all necessary files and directories are easily accessible.
pkgList
.startup.m
script as you add or remove packages.startup.m
and root_programs.m
files, especially if working in a team environment.By following these instructions, you can streamline your MATLAB environment setup, making it easier to work with multiple projects and packages.
root_programs.m
function str = root_programs()
% root_programs - Determines the root directory for programs.
%
% This function computes the root directory for storing or accessing
% programs. The path is determined based on the operating system.
% For Windows, it derives the path from the user's MATLAB userpath.
% For non-Windows systems, it defaults to the user's home directory.
%
% Output:
% str - A string representing the computed root directory path.
% Check if the operating system is Windows
if ispc
% Obtain the user's MATLAB userpath
usr_path = userpath;
% Split the userpath to extract components
path_comp = split(usr_path, filesep); % Using filesep for OS compatibility
% Construct the root path from the first three components
% This assumes the userpath follows a specific structure
str = fullfile(path_comp{1}, path_comp{2}, path_comp{3});
else
% For non-Windows systems, use the user's home directory
str = '~';
end
end
startup.m
% Check if the script is running in a deployed (compiled) environment
% If so, skip the rest of the script as path additions are not necessary
if isdeployed
return
end
% Set a breakpoint for all errors - MATLAB will pause execution whenever an error occurs
dbstop if error
% Define the root directory for programming projects
rootProgramming = fullfile(root_programs, 'git', 'programming');
% List of packages to be added to MATLAB's path
% These are assumed to be subdirectories within the rootProgramming directory
pkgList = {...
'hydra-image-processor';
'matlab-utilities';
'direct-5D-viewer';
'hmm-bayes'
};
% Call the function to add specified paths to MATLAB's search path
addPaths(rootProgramming, pkgList);
% Function to add paths
function addPaths(rootProgramming, pkgList)
% Subdirectory names within each package where MATLAB files are located
matlabDir = fullfile('src','MATLAB');
matlabDir_l = fullfile('src','matlab');
% Loop through each package in the list
for i = 1:length(pkgList)
% Construct the full path to the MATLAB directory in the package
pkgPath = fullfile(rootProgramming, pkgList{i}, matlabDir);
% Add the path if it exists
if exist(pkgPath, 'dir')
addpath(pkgPath);
else
% Check for an alternate path (lowercase 'matlab')
pkgPath = fullfile(rootProgramming, pkgList{i}, matlabDir_l);
if exist(pkgPath, 'dir')
addpath(pkgPath);
end
end
end
end
I put all of my git repositories in a master directory, which is stated in the first line.
I have many different packages that I use, so a list of the repository names goes in the package list.
If you have looked at any of my other repositories, I like to have a standard subdirectory hierarchy.
The folder named src
indicates where source code goes.
the second folder MATLAB
indicates that this is MATLAB code.
I then go through all of my packages and add them to my MATLAB path.
This allows me to have access to each of the packages from the MATLAB command line regardless of which directory I'm currently in.
I highly recommend this method. It also helps when you use some of my other various repositories that depend on this one :smiley:.
This package includes the jar
file for Bioformats that has been tested.
This is only used in the MicroscopeData.Original
package and is not strictly needed for this repository to be useful.
If you would like to use a newer version of the Bioformats functions or would like to compile your own version, please visit their website.
Also, a version of the Keller Lab Block Format is included. If you would like versions for you particular operating system or would just like to compile the most current version, please visit their website.
The most heavily used package in this repository is MicroscopeData.
This package is how I read and write microscope image data where my other repositories can read them in a predictable way.
MicroscopeData.Original
wraps the MATLAB version of Bioformats in such a way that the image and meta-data are returned exactly as the ones written by the MicroscopeData
writers.
The main idea is to read and write 5-D image dataset in multiple file formats with the same MATLAB commands. For example:
[im,imMeta] = MicroscopeData.Reader();
Or alternatively:
[im,imMeta] = MicroscopeData.Reader('C:\pathToJsonFile');
This is the hallmark function of this repository.
Many different file types can be written out by the included code using the particular writers, but reading is as simple as calling the Reader
command.
This is accomplished by having a set of minimal meta-data stored in a json file that is in the same directory as the image files.
The contents of this json file is enough to know how to read the files and reconstruct the data.
The reader will always return the image data as a 5-D matrix where unused dimensions are singleton.
The ordering of this matrix is always (y,x,z,λ,t), where λ is the discrete channels.
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
Eric Wait -- Architect and maintainer -- Eric Wait.com
Andrew Cohen -- Initial Funder and contributor -- Bioimage
Mark Winter -- Contributor and consultant
Blair Rossetti -- Contributor
See also the list of contributors who participated in this project.
This project is licensed under the BSD License - see the LICENSE.md file for details