Giter VIP home page Giter VIP logo

czi-tools's Introduction

CZI Extractor Build Status

Software for extracting images and metadata from Carl Zeiss Images (.czi files). This format is in use in microscopy.

Note: This software does not edit or produce any .czi files; it only reads data from already-existing .czis.

Requirements

These tools require a modern Unix-like system to run. We have limited resources for conducting testing on different platforms, so the list of platform-specific instructions below is very incomplete.

vips

The region stitching tools require vips version 8 or greater.

Ubuntu/Debian

Users of Ubuntu Xenial and later and users of Debian can install vips running the following command as root:

apt-get install libvips-dev

Older versions of Ubuntu require building recent vips from source, instructions for which can be found here.

Fedora

Users of Fedora should run the following command as root:

dnf install vips vips-devel

macOS

Vips can be installed on macOS using Homebrew:

brew install vips --with-imagemagick --without-graphicsmagick --with-openexr --with-openslide

Other operating systems

Other operating systems may provide packages for vips, however building from source will be required if no packages are provided.

JxrDecApp

Microsoft's JPEG-XR decoding tool JxrDecApp is required by the batch processing scripts on the system's PATH. Some operating systems may have a package for this, or it can be built from source (only JxrDecApp is required from this codebase, so all necessary building can be done using make JxrDecApp).

czinspect

The czinspect application requires the used of the xxd(1) tool, which is distributed with vim, for processing application usage messages.

Compiler

The build system for czinspect assumes you are using a reasonably recent version of GCC or Clang which exposes the __BYTE_ORDER__ macro. Note that on OpenBSD systems this may require installing a newer compiler from packages if you are using a system where the default base compiler is still GCC 4.2.1.

Building

Building should be as simple as

make

Note: due to a conflict in different ld implementations, MacOS cannot build this project right now.

Tests are also available:

make test

To move all of the built binaries to the bin folder:

make bin

Running

Binaries

Each of the utility programs can be found in the appropriate src subfolder.

Documentation for the use of these utilities is currently non-existant. All utilities have help-text that should be kept up-to-date:

get_region -h
czinspect  -h

Scripts

Some utility scripts have been supplied in the bin folder:

  • batch.sh is a script designed to batch-process a bunch of .czi files at once.
  • czi2png.sh, jxr2png.sh, and deczi-extracjxr.sh are old scripts no longer used.

Example Use

Batch Conversion

You have a directory of .czi files called czi-folder, and you want to extract every image tile (converted to .pngs) from each of these files into respective subdirectories under the directory extracted-tiles:

batch.sh -Ed "extracted-tiles" "czi-folder"

Each set of .pngs will turn up in a subdirectory of extracted-tiles named after the .czi file they came from.

Retreive Specific Region of Image

You've extracted a .czi image, the output being a collection of .tif images residing in the directory all-extracted, and now you want a 123x789-sized region with its top-left corner at x-y coordinate 3030,2929 of the whole image. Additionally, you want the output to be a .png called my-region.png, and the output image to be at zoom level 8. The appropriate command would be:

get_region -i "all-extracted" -l 3030 -u 2929 -r 3153 -d 3718 -o "my-region.png" -z 8

Credits

This code is actively developed by Molly Miller and Tom Harley, and is based on work by Calum Duff for a project with a team including Johannes Weck, Hafeez Abdul Rehaman and Josh Lee.

czi-tools's People

Contributors

magnostherobot avatar sysvinit avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

czi-tools's Issues

czinspect: support metadata dumping

extractjxr supports dumping a .czi file's metadata to a file (currently using a shoddy, hand-rolled JSON formatter), which a gives a human readable and pre-prepared representation of the file's metadata. czinspect should implement this (or something similar) to attain feature parity.

czinspect: implement subsampling ratio scanning and filtering

czinspect does not yet support subsampling ratio scanning for .czi files, which is required both as an informational feature and for filtering certain levels of the stored image pyramid when extracting image tiles.

Additionally, it is desirable for czinspect to be able to automatically guess the nearest subsampling level if given a level which does not exist in the file, so that a number of images can be extracted in bulk without having to scan all of them and set appropriate filter levels.

czinspect: fix macOS build

The CI builds for czinspect on macOS fail when creating the object files for the help files, due to the linker not recognising the flags in use. macOS also uses the Mach-O executable format instead of ELF, so the help text handling may need completely rewritten.

czinspect: support metadata consistency checking

The ability to perform a sanity check of the metadata in a .czi file (i.e. that the metadata held in the ZISRAWDIRECTORY segment and the ZISRAWSUBBLOCK segments matches) would be a useful feature for troubleshooting issues in extracting images from the file.

czinspect: refine dynamic data structure handling

czinspect has two forms of dynamic data structure, the lzstring and the lzbuf; the former implements dynamically allocated null-terminated strings and the latter implements dynamically allocated array of a given type. Internally these are implemented as macros over the same family of functions and structures. However, all that the underlying structure keeps track of is a pointer to an area on the heap and the length of this area; there is no mechanism for tracking how much of this area is in use. This causes issues when passing these structures (or pointers to them) through several different functions when used as array, as the length must be passed separately.

lzstring and lzbuf have different purposes, therefore their implementations should probably be seperate.

czinspect: fix operation on big-endian systems

A cursory test of czinspect on an OpenBSD/macppc system shows that the big endian compatibility code does not function correctly. This problem has not yet been investigated in depth.

czinspect: extract specific tiles from a .czi file

There are potential use cases where extracting only a few specific tiles from a .czi file would be desirable, such as inspecting image regions which cross tile edges. An external tool could examine dumped metadata (see #4), calculate the required tiles and then execute czinspect to extract only those tiles.

czinspect: concurrency support

czinspect currently extracts tiles from an image in serial order; on systems with multiple cores and high-throughput I/O, extraction speed may be increased by extracting several tiles from an image file at once.

czinspect: perform in-line conversion from JPEG-XR to other formats

The image format used by tiles in a .czi file is usually JPEG-XR, which is unwieldy for a lot of applications as the image format is not common, which necessitates format conversion. Adding support for czinspect to do this in-line after extraction would remove the need for external tooling to do this after the fact.

The proposed model is to extract a JXR image tile and then fork+exec JxrDecApp from jxrlib to convert to TIFF. Further conversions could then be performed with other programs such as vips or ImageMagick's convert.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.