mcdlib

MCD file parser library

Features

• Full metadata access
• Slide image extraction
• Panorama image extraction
• Acquisition image extraction
• Binary data access (in-memory)
• OME-TIFF export (optional compression)
• Unit test environment
• Python 3 bindings

Prerequisites

• pugixml
  http://www.pugixml.org
  Bundled with the source (version 1.8)
  Header-only library, no additional setup required

• OME Files (optional, for OME-TIFF support)
  http://www.openmicroscopy.org/site/products/ome-files-cpp
  Required components: OME Common, OME Model, OME Files
  Build and install with cmake & make & sudo make install
  Tested with OME Common 5.4.2, OME Model 5.5.6 and OME Files 0.4.0

• Google Test (optional, for unit test support)
  https://github.com/google/googletest
  Configured as a Git submodule, no additional setup required

• pybind11 (optional, for Python support)
  https://github.com/pybind/pybind11
  Configured as a Git submodule, no additional setup required

Installation

git clone --recursive https://github.com/BodenmillerGroup/mcdlib.git
mkdir mcdlib/cmake-build-release
cd mcdlib/cmake-build-release
cmake -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install
sudo ldconfig

Note: if you experience troubles while building the library (more specifically, when linking mcdlib to the OME libraries), this likely happens because of outdated/broken CMake files provided by the Open Microscopy Environment (OME) team.

Usage

This is a C++11 example of the full functionality of the library:

#include <string>

#define OMETIFF_SUPPORT_ENABLED
#include <mcdlib/MCDFile.h>

int main(int argc, char *argv[]) {
    mcd::MCDFile mcdFile("/path/to/file");

    // full metadata access
    auto meta = mcdFile.readMetadata();
    auto firstSlide = meta.getSlides()[0];
    const std::string schemaXML = meta.getSchemaXML();
    auto swVersion = firstSlide->getProperty("SwVersion");

    // slide image extraction
    mcdFile.saveSlideImage(firstSlide, "/path/to/file");

    // panorama image extraction
    auto firstPanorama = firstSlide->getPanoramas()[0];
    mcdFile.savePanoramaImage(firstPanorama, "/path/to/file");

    // before/after acquisition image extraction
    auto firstRegion = firstPanorama->getRegions()[0];
    auto firstAcquisition = firstRegion->getAcquisitions()[0];
    mcdFile.saveAcquisitionImage(firstAcquisition, "/path/to/file", mcd::MCDFile::AcquisitionImageType::BEFORE);

    // acquisition data export to OME-TIFF
    std::string compression = "LZW";
    auto data = mcdFile.readAcquisitionData(firstAcquisition);
    data.writeOMETIFF("/path/to/file", &compression);

    // in-memory acquisition data access
    auto firstChannel = firstAcquisition->getChannels()[0];
    auto firstChannelData = data.findChannelData(firstChannel);
    auto firstChannelDataRaw = firstChannelData->getData();

    return 0;
}

For interactive/scripting usage, this is a Python 3 example:

import mcdpy
mcd = mcdpy.MCDFile('/path/to/file')

# full metadata access
meta = mcd.readMetadata()
first_slide = meta.slides[0]
print(first_slide.properties['SwVersion'])
print(meta.schemaXML)

# slide image extraction
mcd.saveSlideImage(first_slide, '/path/to/file')

# panorama image extraction
first_panorama = first_slide.panoramas[0]
mcd.savePanoramaImage(first_panorama, '/path/to/file')

# before/after acquisition image extraction
first_region = first_panorama.regions[0]
first_acquisition = first_region.acquisitions[0]
mcd.saveAcquisitionImage(first_acquisition, '/path/to/file', mcdpy.AcquisitionImageType.BEFORE)
mcd.saveAcquisitionImage(first_acquisition, '/path/to/file', mcdpy.AcquisitionImageType.AFTER)

# acquisition data export to OME-TIFF
data = mcd.readAcquisitionData(first_acquisition)
data.writeOMETIFF('/path/to/file.ome.tiff')
data.writeOMETIFFCompressed('/path/to/file.ome.tiff', 'LZW')

# in-memory acquisition data access
first_channel = first_acquisition.channels[0]
channel_data = data.findChannelData(first_channel)
raw_channel_data = channel_data.data

At any time, a brief documentation is available using Python's built-in help functionality.

License

Copyright 2017 Jonas Windhager

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.