diff --git a/README.md b/README.md index 22e0dfd..7d8597e 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,61 @@ By default, mpm installs all Matlab packages to the directory `mpm-packages/`. ( If you restart Matlab, you'll want to run `mpm init` to re-add all the folders in the installation directory to your Matlab path. Better yet, just run `mpm init` from your Matlab [startup script](http://www.mathworks.com/help/matlab/ref/startup.html). +## mpmimport + +`mpmimport` is an experimental function meant to approximate the `import package` namespace management features in most modern languages (modeled after Python). +In languages such as Python, you must explicitely state which packages and functions you want your current script to have access to by adding `import XXX` statements to the top of the script (or in your console). This allows you to control the global namespace, prevent silent name clashes (two functions with the same name on your matlab path that do different things) and be generally explicit about what your script requires (better for sharing your code with others or future you...). The `mpm` package manager provides excellent facilities for automatically downloading packages and adding them to a standard location, and `mpmimport` is meant to compliment this by dynamically adding packages to your path as needed. + +For example, install `imstack` from matlab file exchange (https://www.mathworks.com/matlabcentral/fileexchange/55546-imstack) without modifying the path (using the `--nopaths` flag): + +``` matlab +mpm install imstack --nopaths +``` + +Now, one of the main functions in `imstack` is `addRoiToolbar`. To confirm that it is not on your path at the moment, type the following into the matlab console: + +``` matlab +help addRoiToolbar +``` +Returns: + +``` matlab +addRoiToolbar not found. + +Use the Help browser search field to search the documentation, or +type "help help" for help command options, such as help for methods. +``` + +Now run the following in the console: + +``` matlab +mpmimport("imstack") +``` + +When you type repeat the help query above, you should see the following now: + +``` matlab +help addRoiToolbar +``` +Returns: + +``` matlab + + addRoiToolbar + Add a toolbar for creating ROIs like Line Ellipse Rectangle Polygon and Freehand + Right-click the ROIs to open a context menu, and you will see more + functions there such as histogram, x-y plot, etc. + Example: + + load mri; + imshow(D(:,:,14)) + addRoiToolbar; +``` + +Note that the path will be modified for the duration of the session if you run this in a script or in the console. + + + ## Troubleshooting Because there's no standard directory structure for a Matlab package, automatically adding paths can get a bit messy. When mpm downloads a package, it adds a single folder within that package to your Matlab path. If there are no `*.m` files in the package's base directory, it looks in folders called 'bin', 'src', 'lib', or 'code' instead. You can specify the name of an internal directory by passing in an `-n` or `internaldir` argument. diff --git a/mpmimport.m b/mpmimport.m new file mode 100644 index 0000000..6899319 --- /dev/null +++ b/mpmimport.m @@ -0,0 +1,39 @@ +function mpmimport(pkg) +%mpmimport adds specific packages/functions installed with mpm to the global path +% Very simple function. Given one or more packages, mpmimport will look +% in the directory specified in mpm_config() for the metadata file, and +% load that package's path into the current session. + +opts = mpm_config(); % load the options to get dirs. +try +metadata_f = fullfile(opts.DEFAULT_INSTALL_DIR, 'mpm.mat'); +metadata = load(metadata_f); +catch + warning("Couldnt find metadata file in default location: ") + error(metadata_f); +end +metadata = metadata.packages; +pkg_path = find_pkg(pkg, metadata); +if strcmp(pkg_path, "Not present") + fprintf("package %s not found. Try: 'mpm install %s'\n",pkg, pkg); + error("package not found error"); +else +fprintf("adding %s to path\n", pkg); % remove after debugging +addpath(pkg_path) +end +end + +% function below searches th +function path = find_pkg(pkg_nm, pkg_list) +[~,pkgs] = size(pkg_list); +for ii=1:pkgs + n = string(pkg_list(ii).name); + if strcmp(n,pkg_nm) + path = pkg_list(ii).installdir; + return + else + path = "Not present"; + end +end +end + diff --git a/tests/verifyImportTest.m b/tests/verifyImportTest.m new file mode 100644 index 0000000..0a7f39a --- /dev/null +++ b/tests/verifyImportTest.m @@ -0,0 +1,14 @@ +%% future unit tests here. +% !!!! not currently functional !!! +mpm install imstack % install package +opts = mpm_config(); % load the options to get dirs. +metadata_f = fullfile(opts.DEFAULT_INSTALL_DIR, 'mpm.mat'); +metadata = load(metadata_f); +metadata = metadata.packages; +[~,sz] = size(metadata); +for i=1:sz + n = metadata(i).name; + if strcmp(n,'imtools') + disp(n); + end +end