Open Microscopy Environment

Hi, I'm writing a MATLAB function `bfTiffComment.m` that'll help verification and editing of OME-XML metadata.

bfTiffComment.m

https://github.com/ome/bio-formats-tool ... idate.java

In this function, in order to get access to `loci.formats.tools.TiffComment`class, which is the main part, I relied on `bfCheckJavaPath`.

It works, but I realized that it does not work with ImageJ-MATLAB. When launching ImageJ-MATLAB, the jar files in `Fiji.app\jars`are added to MATLAB dynamic Java class path. This includes `formats-bsd-5.9.2.jar'`. Looking into this jar file by Java decompiler, this jar file contains the `loci.formats.tools` package, but the `loci.formats.tools` does not contain `TiffComment` or `XMLvalidate` class.

`bfCheckJavaPath` apparently cannot handle this properly. So, when I call `loci.formats.tools.TiffComment`class, I get an error.

Why the Bio-Formats for Fiji is designed in this way? Why only some of the classes are missing from `loci.formats.tools`package in `formats-bsd-5.9.2.jar`?

More practically, is there a workaround for this for us to use ImageJ-MATLAB and `loci.formats.tools.TiffComment` at the same time?

Best,
Kouichi

Hi Kouichi,

this page describes the various components of Bio-Formats and their scope. Briefly

• formats-bsd and formats-gpl contain the file format readers
• bio-formats-tools contains the classes targetted for the command-line interface
• bio-formats-plugins contains the classes allowing to consume the Bio-Formats API as an ImageJ plugin

The Fiji distribution only ships the bio-formats-plugins JAR and its dependencies: formats-bsd and formats-gpl while the TiffComment and XMLValidate command-line utilities are shipped with the command-line tools bundle.

If you want to make the command-line tools available in the conditions you describe (MATLAB started from the ImageJ-MATLAB interface of Fiji), your options are:

• add the bio-formats-tools JAR to your Fiji distribution i.e. under jars/bio-formats
• add bio-formats-tools to your dynamic MATLAB classpath
• use the bioformats_package uber JAR instead of the individual JARs

A more general question is whether wrapping these classes is the most effective way to achive what you want. Extending the MATLAB toolbox to mirror the utilities like `tiffcomment` would be very valuable and we are extremely glad to see you driving this. The command-line tool utility classes like TiffComment and XMLValidate are designed to handle the argument parsing/validation and error/logger handling but the core calls are all delegated to the low-level Bio-Formats API. In MATLAB, there is no reason the same cannot be done by writing all the argument parsing and error/return handling using MATLAB built-in functionalities like in bfopen. We would be happy to hear your thoughts on this.

Best,
Sebastien

Hi Sebastien. Thank you for the reply.

I tried the Command line tools. For a MATLAB user, Command line tools are bound to be used with MATLAB's `system` function. Writing wrapper MATLAB function for Command line tools is actually easy. But they don't come with Bio-Formats MATLAB toolbox, so it's a bit awkward to think about where to store the new function (should it be with Command line tools or Bio-Formats MATLAB toolbox? Neither seems ideal).

I should have known earlier but I just recently (yesterdayish) realized that `bfopen` and `bfsave` can actually handle OME-XML. With them, the point of having the new `bfTiiComment.m` may be that it allows us to extract or inject OME-XML without loading or saving image data, and also allows us to validate OME-XML.

So I thought if I can write `bfTiiComment.m` just relying on Bio-Formats MATLAB toolbox, then it will replace the Command line tools for these purposes.

Now, you gave me three choices, but none of them allow me to achieve what I wanted. If I need to rely on `bio-formats-tools.jar` (I don't know how to get it) in addition to Bio-Formats MATLAB toolbox, it's not that different from using a wrapper function for Command line tools. Replacing individual jars for Fiji with`bioformats_package.jar` is also a bit cumbersome (I don't know exactly which jar files in Fiji should be replaced).

So, yeah, I think I'm a bit disappointed about this. My plan was to make a Pull Request for `bfTiiComment.m` to be added to Bio-Formats MATLAB toolbox, but I'm no longer sure it's worthwhile if it doesn't work straight away with ImageJ.

Hi Kouichi,

this is the current content of the high-level bundles available from the the Bio-Formats downloads

• the Fiji Java 8 update site ships the minimal subset of Bio-Formats components required for the ImageJ usage (formats-api, formats-bsd, formats-gpl, bio-formats-plugins),
• the MATLAB bundle ships all Bio-Formats components bundled in the bioformats_package JAR (formats-api, formats-bsd, formats-gpl, bio-formats-plugins, bio-formats-tools) as well as a wrapper MATLAB functions using the API (bfopen.m, bfsave.m),
• the Command line tools ships the Bio-Formats components bundled in the bioformats_package JAR (formats-api, formats-bsd, formats-gpl, bio-formats-plugins, bio-formats-tools) as well as wrapper shell scripts invoking the utility classes from the bio-formats-tools componnent.

If using the MATLAB toolbox directly, the wrapper shell scripts are not included but the command-line tools Java classes should be part of the bundle. ImageJ-MATLAB is an environment that we have not tested when implementing these functionalities. There are different ways to use ImageJ-MATLAB it. Are you running ImageJ within MATLAB or using the scripting enging? How are you including the MATLAB scripts which are not part of the ImageJ distribution?

Expanding on my last comment, it should be possible to write `bfTiffComment` without requiring the bio-formats-tools at all but only the components shipped with Fiji. For instance below is a minimal example which should return the comment from the first IFD of a TIFF file:

Code: Select all

% Initialize logging
bfCheckJavaPath();
bfInitLogging();
% Create TiffParser, extra comment and close resources
tp = loci.formats.tiff.TiffParser(file);
comment = tp.getComment();
tp.getStream().close();


Best,
Sebastien

There are different ways to use ImageJ-MATLAB it. Are you running ImageJ within MATLAB or using the scripting enging? How are you including the MATLAB scripts which are not part of the ImageJ distribution?

Yes, you can run MATLAB scripts form within Fiji, but I found that this is not very useful.

* It launches MATLAB anyway, so first time execution takes time.
* MATLAB is in 'virgin' state, i.e. MATLAB search path is back to the default. You can't access external toolboxes or your own routine functions (unless you use addpath explicitly).
* A special care must be taken to the handling of file path, this is because the code is executed using eval essentially. In Windows, you need to escape the file separators.

So, most of the time, I launch Fiji from MATLAB.

Thanks for the code example. At least XML extraction is doable then.

Indentation and validation may still be tricky.

Just a thought, but why do we need the 'basic' version rather than full 'bioformats_package.jar' for Fiji? If the full version is there, then I don't have to worry about the differences.

Hi Kouichi,

trying to use individual JARs rather than full bundle is a general policy of the Fiji distribution. This is primarily driven by the complexity of the ecosystem and the need to management plugins that might share common dependencies. You can read more on the topic here.

Best,
Sebastien

Right. I decided to implement a detailed error message with an instruction to use bioformats_package.jar for Fiji. I understand that using minimal jar is the policy. But does using bioformats_package.jar have any side effects? So far, it seems that both ImageJ and bfTiffComment are working.

Code: Select all

status = bfCheckJavaPath(1);
assert(status, ['Missing Bio-Formats library. Either add bioformats_package.jar '...
    'to the static Java path or add it to the Matlab path.']);
%NOTE bfCheckJavaPath does not work with ImageJ-MATLAB

try
    TC = loci.formats.tools.TiffComment;
    isbioformats_package_loaded = true;
    isformats_bsd_loaded = false;
catch exc1
   
    % http://www.openmicroscopy.org/community/viewtopic.php?f=13&t=8636#p20303
   
    if strcmp(exc1.message,'Undefined variable "loci" or class "loci.formats.tools.TiffComment". ')
        error(['Although Bio-Formats are available, could not access "loci.formats.tools.TiffComment" classs. ',...
            'This can be because ImageJ-MATLAB is being used, and only part of Java classes of Bio-Formats are added to the dynamic Java class path. ',...
            'See the <a href="http://www.openmicroscopy.org/community/viewtopic.php?f=13&t=8636#p20303">discussion here for more details</a>. ',...
            '\n\n',...
            'If this is the case, to fix this, you can delete all the .jar files in the folder "%s" (FIji) or "%s" (ImageJ), ',...
            'and instead copy the all inclusive "bioformats_package.jar" in Bio-Formats MATLAB toolbox "%s" to the "bio-formats" folder mentioned above.'],...
            fullfile('Fiji.app','jars','bio-formats'),...
            fullfile('ImageJ.app','jars','bio-formats'),...
            fullfile(fileparts(which('bfopen')),'bioformats_package.jar'))
       
    else
       throw(exc1)
    end
end


Using bioformats_package.jar will work fine, the potential downside of using it is that it can potentially cause dependency conflicts with some other FIJI plugins.