Opening OME TIFF files without `.ome.tif` extension

OMETIFF.jl

Stable Release	Documentation	Build Status

Adds support for reading OME-TIFF files to the Images.jl platform. Allows fast and easy interfacing with high-dimensional data with nice labeled axes provided by AxisArrays.jl.

Features

Can open a wide-range of OMETIFF files with a special focus on correctness
Supports memory-mapping to open large TIFF files quickly even on memory-constrained machines
Spatial and temporal axes are annotated with units if available (like μm, s, etc)
Channel and position axes use their original names
Elapsed times are extracted and returned using the same labeled axes
Important metadata is extracted and included in an easy to access format

Installation

OMETIFF.jl will be automatically installed when you use FileIO to open an OME-TIFF file. You can also install it by running the following in the Julia REPL:

] add OMETIFF

Usage

julia> using FileIO, Images

julia> img = load("/Users/tamasnagy/Downloads/66perc-h2o-vs-iso_1_MMStack.ome.tif")
Gray ImageMeta with:
  data: 4-dimensional AxisArray{Gray{N0f16},4,...} with axes:
    :y, 0.0 μm:0.6518 μm:666.7914000000001 μm
    :x, 0.0 μm:0.6518 μm:666.7914000000001 μm
    :time, 0.0 ms:15000.0 ms:405000.0 ms
    :position, Symbol[:A5_Site_0, :A5_Site_1, :B5_Site_0, :B5_Site_1]
And data, a 1024×1024×28×4 reshape(reinterpret(Gray{N0f16}, ::Array{UInt16,6}), 1024, 1024, 28, 4) with eltype Gray{Normed{UInt16,16}}
  properties:
    Elapsed_Times: Unitful.Quantity{Float64,𝐓,Unitful.FreeUnits{(s,),𝐓,nothing}}[2.525 s 3.35 s 5.638 s 6.534 s; 15.398 s 16.195 s 18.743 s 19.506 s; … ; 390.389 s 391.154 s 393.282 s 393.984 s; 405.391 s 406.13 s 408.316 s 409.101 s]
    Description: nd4 + nd8 in

julia> size(img) # lets get the dimensions
(1024, 1024, 28, 4)

julia> axisnames(img) # wait, but what do they correspond to?
(:y, :x, :time, :position)

julia> img[Axis{:position}(:A5_Site_1), Axis{:time}(2)]; # get the 2nd time point in position A5

julia> img["Elapsed_Times"][Axis{:position}(:A5_Site_1), Axis{:time}(2)] # get exact time when that slice was taken
16.195 s

julia> img["Description"] # get any notes embedded in the image
"nd4 + nd8 in"

More advanced usage

The image updates all the axes as we subset it. Observe that since we're grabbing 5x5x1x1 subset of the image, all the axes update to reflect this slice.

julia> using Unitful

julia> img[Axis{:y}(1:5), Axis{:x}(1:5), Axis{:time}(15000u"ms"), Axis{:position}(1)]
Gray ImageMeta with:
  data: 2-dimensional AxisArray{Gray{N0f16},2,...} with axes:
    :y, 0.0 μm:0.6518 μm:2.6072 μm
    :x, 0.0 μm:0.6518 μm:2.6072 μm
And data, a 5×5 Array{Gray{N0f16},2} with eltype Gray{Normed{UInt16,16}}
  properties:
    Elapsed_Times: Quantity{Float64,𝐓,Unitful.FreeUnits{(s,),𝐓,nothing}}[2.525 s 3.35 s 5.638 s 6.534 s; 15.398 s 16.195 s 18.743 s 19.506 s; … ; 390.389 s 391.154 s 393.282 s 393.984 s; 405.391 s 406.13 s 408.316 s 409.101 s]
    Description: nd4 + nd8 in

Dumping embedded OME-XML

To quickly access the OME-XML stored inside a TIFF file, use the OMETIFF.dump_omexml function:

julia> using OMETIFF

julia> println(OMETIFF.dump_omexml("test/testdata/singles/single-channel.ome.tif"))
<OME xmlns="http://www.openmicroscopy.org/Schemas/OME/2016-06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Creator="OME Bio-Formats 5.2.2" UUID="urn:uuid:2bc2aa39-30d2-44ee-8399-c513492dd5de" xsi:schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2016-06 http://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd">
  <Image ID="Image:0" Name="single-channel.ome.tif">
    <Pixels BigEndian="true" DimensionOrder="XYZCT" ID="Pixels:0" SizeC="1" SizeT="1" SizeX="439" SizeY="167" SizeZ="1" Type="int8">
      <Channel ID="Channel:0:0" SamplesPerPixel="1">
        <LightPath/>
      </Channel>
      <TiffData FirstC="0" FirstT="0" FirstZ="0" IFD="0" PlaneCount="1">
        <UUID FileName="single-channel.ome.tif">urn:uuid:2bc2aa39-30d2-44ee-8399-c513492dd5de</UUID>
      </TiffData>
    </Pixels>
  </Image>
</OME>

	# if the data is stripped and we haven't fix tmp's layout then lets make
	# tmp equal to one strip. This'll be fixed in Julia 1.4
	if n_strips > 1 && size(tmp) != (strip_len, )
	tmp = Array{rawtype}(undef, strip_len)
	end

	# if this file isn't one we've observed before, increment the offset
	if !in(filepath, obs_filepaths)
	ifd = file_ifd_offset
	file_ifd_offset += 1
	push!(obs_filepaths, filepath)
	end

	metadata = JSON.parse(String(metadata_bytes))
	if !haskey(metadata, "Summary")
	return ""
	end
	metadata["Summary"]

	@test size(img) == (167, 439, 3, 7)
	# check channel indexing
	@test size(img[Axis{:channel}(:C1)]) == (167, 439, 7)
	# check time indexing
	@test size(img[Axis{:time}(1)]) == (167, 439, 3)

	# This is an ugly hack to convert the unit string into Unitful.Unit till
	# https://github.com/PainterQubits/Unitful.jl/issues/214 gets fixed
	unittype = @eval @u_str $(image[units])

	# Create a unitful range
	return 0unittype:incrementunittype:increment(dimsize-1)unittype

	function TiffFile(uuid::String, filepath::String)
	file = TiffFile(open(filepath))

	unused_dims = Tuple(idx for (idx, key) in enumerate(keys(dims)) if dims[idx] == 1)
	squeezed_data = dropdims(data; dims=unused_dims)
	used_axes = [axes[i] for i in 1:length(axes) if !(i in unused_dims)]

	# TODO: This shouldn't be allocated for each ifd
	tmp = Array{master_rawtype}(undef, read_dims...)

	# This is an ugly hack to convert the unit string into Unitful.Unit till
	# https://github.com/PainterQubits/Unitful.jl/issues/214 gets fixed
	unitstr = replace(image[units], "u" => "μ")

tlnagy / ometiff.jl Goto Github PK

ometiff.jl's Introduction

OMETIFF.jl

Features

Installation

Usage

More advanced usage

Dumping embedded OME-XML

ometiff.jl's People

Contributors

Stargazers

Watchers

Forkers

ometiff.jl's Issues

Recommend Projects

Recommend Topics

Recommend Org