How to save labelings with metadata in ImageJ / Fiji

Hi all,

we are trying to figure out the best way from Java to save labelings to disk.

In my specific case, I would like to save a LabelEditor scene including sources, labelings and colors, give the file to a collaborator who drags it into Fiji and gets the same LabelEditor view.


  • storing labeling: a labeling consists of pixels associated with a set of labels ( = labels can overlap); a labeling can be sparse or dense
  • storing metadata: a labeling has additional information, e.g. a label has tags, a tag has a color; the user might want to assign metadata to the labeling independently for each timestep


  • storing grouped data: the user can store multiple labelings with metadata and associated images (raw image, propability map, …) together
  • compatibility: at least parts of the format can be opened with other libraries / softwares



  • save index image and list of label sets belonging to each index, e.g. TIFF and JSON / XML
  • save JSON / XML with size of dataset and a list of pixels associated with each label (good for sparse labeling)


  • save metadata as additional JSON / XML / CSV with label as id
  • save metadata in TIFF header (?)


  • use CSV as entry point: listing labels, linking index source, linking metadata files, … (readable by other tools, but this is also similar to inventing our own format)
  • use N5 (one compressed file, simple API)
  • use a script (would not require to come up with an extra format, but there will be multiple files and the script needs to be written first)

We are leaning towards N5 with index images (plus optionally sources) and JSON files for storing the labels and the metadata. We would need to come up with a spec for how to structure our N5 if none exists for this use case. We would like to know if we are missing something and who else we should talk to to not have multiple formats for the same thing. What about OME / Bio-Formats? Any opinions?

@maarzt @tpietzsch @haesleinhuepf @axtimwalde @Christian_Tischer @kephale @NicoKiaru @joshmoore @imagejan @ctrueden



I have been storing SciView scenes and analysis metadata in n5. One thing I that I end up doing, which isn’t great, is somewhat arbitrarily switching between what information I store in attributes and blocks depending on what is most convenient to the respective project.

I’ve heard some other concerns about lack of consistency in how n5 attributes are handled/named. Maybe this is related to the previous work on RichImg’s…

1 Like

Hello @frauzufall,

Thanks for starting this discussion!
Not saying it’s ideal, but couldn’t most of this be done with SpimData objects + their extensibility mechanisms ?

I have to say I’m not familiar with n5, so probably what I suggest is outdated.