BioLib.Zarr Class Reference

Bridges BioLib's BioImage to the OmeZarrWriter, exporting a full 5D image as an OME-Zarr v3 dataset on local disk. More...

Static Public Member Functions
static async void	SaveZarr (BioImage b, string outputDir)
	Saves the full 5D content of a BioImage as an OME-Zarr v3 dataset at outputDir . All pyramid resolution levels in b.Resolutions are written.
static async Task	SavePyramidalZarr (BioImage[] levels, string outputDir)
	Saves already-processed pyramid levels as an OME-Zarr multiscale dataset. Each entry in levels is written as one resolution level in the output pyramid.
static void	SaveROIs (BioImage b, string outputDir)
	Writes all annotations on b as a JSON sidecar file at <outputDir>/rois.json.
static List< ROI >	LoadROIs (string zarrDir)
	Reads <zarrDir>/rois.json and returns the deserialized list of ROI objects. Returns an empty list when no sidecar file exists.
static List< ROI >	LoadLabelsAsROIs (BioImage b, string zarrDir)
	Reads every label image stored under <zarrDir>/labels/ according to the OME-NGFF labels spec and converts each unique non-zero integer label ID into a ROI of type ROI.Type.Mask.

Static Public Attributes
const string	RoiFileName = "rois.json"
	The file name used for the ROI sidecar that sits beside the Zarr dataset.

Detailed Description

Bridges BioLib's BioImage to the OmeZarrWriter, exporting a full 5D image as an OME-Zarr v3 dataset on local disk.

XY planes are written in tile-sized chunks so that even whole-slide images never require a full plane to be resident in memory at once. Peak allocation is bounded to a single tile (tileW × tileH × bytesPerSample).

RGB-interleaved buffers are deinterleaved into separate C planes so the output array shape is always (T, C, Z, Y, X) with scalar pixels.

All resolution levels present in b.Resolutions are written, producing a proper OME-NGFF multiscale pyramid.

Member Function Documentation

LoadLabelsAsROIs()

static List< ROI > BioLib.Zarr.LoadLabelsAsROIs ( BioImage b, string zarrDir )

static

Reads every label image stored under <zarrDir>/labels/ according to the OME-NGFF labels spec and converts each unique non-zero integer label ID into a ROI of type ROI.Type.Mask.

For each label sub-store the finest resolution level (index 0) is read one plane at a time (iterating Z, C, T from the parent b ). Every distinct pixel value > 0 in a plane becomes a separate ROI.Mask whose float array contains 1.0 wherever that label is present and 0.0 elsewhere.

The method is a no-op when no labels/ sub-directory exists, so it is safe to call unconditionally after opening any Zarr store.

Parameters

b	The parent BioImage that supplies physical-size calibration and ZCT extents.
zarrDir	Root path of the Zarr dataset on local disk (the directory that contains zarr.json).

Returns

List of ROI objects (one per unique label ID per plane). Returns an empty list when no labels are found.

        {
            var result = new List<ROI>();
 
            string labelsDir = Path.Combine(zarrDir, "labels");
            if (!Directory.Exists(labelsDir))
                return result;
 
            try
            {
                File.AppendAllText(@"log.txt",
                    "[BioLib.LoadLabelsAsROIs] zarrDir=" + zarrDir +
                    " labelsDirExists=True\n");
            }
            catch { }
 
            // Each sub-directory of labels/ is one label image.
            foreach (string labelPath in Directory.GetDirectories(labelsDir))
            {
                string labelName = Path.GetFileName(labelPath);
                try
                {
                    try
                    {
                        File.AppendAllText(@"log.txt",
                            "[BioLib.LoadLabelsAsROIs] labelPath=" + labelPath +
                            " labelName=" + labelName + "\n");
                    }
                    catch { }
                    result.AddRange(ReadOneLabelStore(b, labelPath, labelName));
                }
                catch (Exception ex)
                {
                    Console.WriteLine($"[Zarr.LoadLabelsAsROIs] Skipping label '{labelName}': {ex.Message}");
                    try
                    {
                        File.AppendAllText(@"log.txt",
                            "[BioLib.LoadLabelsAsROIs] EXCEPTION labelName=" + labelName +
                            " type=" + ex.GetType().Name +
                            " message=" + ex.Message + "\n");
                    }
                    catch { }
                }
            }
 
            Recorder.Record($"Zarr.LoadLabelsAsROIs({b}, \"{zarrDir}\");");
            return result;
        }

LoadROIs()

static List< ROI > BioLib.Zarr.LoadROIs ( string zarrDir )

static

Reads <zarrDir>/rois.json and returns the deserialized list of ROI objects. Returns an empty list when no sidecar file exists.

        {
            var result = new List<ROI>();
            string path = Path.Combine(zarrDir, RoiFileName);
 
            if (!File.Exists(path))
                return result;
 
            string json = File.ReadAllText(path);
            var dtos = JsonSerializer.Deserialize<List<RoiDto>>(json);
            if (dtos == null)
                return result;
 
            foreach (var dto in dtos)
            {
                var an = new ROI
                {
                    roiID      = dto.RoiId,
                    roiName    = dto.RoiName,
                    type       = (ROI.Type)Enum.Parse(typeof(ROI.Type), dto.Type),
                    id         = dto.Id,
                    shapeIndex = dto.ShapeIndex,
                    Text       = dto.Text,
                    serie      = dto.Serie,
                    coord      = new AForge.ZCT(dto.Z, dto.C, dto.T),
                    strokeWidth= dto.StrokeWidth,
                    fontSize   = dto.FontSize,
                };
 
                // Closed shapes
                if (an.type == ROI.Type.Freeform || an.type == ROI.Type.Polygon)
                    an.closed = true;
 
                // Restore colours
                if (!string.IsNullOrEmpty(dto.StrokeColor))
                {
                    var sc = dto.StrokeColor.Split(',');
                    an.strokeColor = AForge.Color.FromArgb(
                        int.Parse(sc[0]), int.Parse(sc[1]),
                        int.Parse(sc[2]), int.Parse(sc[3]));
                }
                if (!string.IsNullOrEmpty(dto.FillColor))
                {
                    var fc = dto.FillColor.Split(',');
                    an.fillColor = AForge.Color.FromArgb(
                        int.Parse(fc[0]), int.Parse(fc[1]),
                        int.Parse(fc[2]), int.Parse(fc[3]));
                }
 
                // Restore points then bounding box
                if (!string.IsNullOrEmpty(dto.Points))
                    an.AddPoints(an.stringToPoints(dto.Points));
 
                an.BoundingBox = new AForge.RectangleD(dto.X, dto.Y, dto.W, dto.H);
 
                result.Add(an);
            }
 
            Recorder.Record($"Zarr.LoadROIs(\"{zarrDir}\");");
            return result;
        }

SavePyramidalZarr()

static async Task BioLib.Zarr.SavePyramidalZarr ( BioImage[] levels, string outputDir )

static

Saves already-processed pyramid levels as an OME-Zarr multiscale dataset. Each entry in levels is written as one resolution level in the output pyramid.

        {
            if (levels == null || levels.Length == 0)
                throw new ArgumentException("No pyramid levels were provided.", nameof(levels));
 
            if (Directory.Exists(outputDir))
                Directory.Delete(outputDir, true);
            if (File.Exists(outputDir))
                File.Delete(outputDir);
 
            var root = levels[0];
            if (root == null)
                throw new ArgumentNullException(nameof(levels));
 
            if (root.SizeX <= 0 || root.SizeY <= 0 || root.SizeZ <= 0 || root.SizeC <= 0 || root.SizeT <= 0)
                throw new InvalidOperationException(
                    $"Invalid pyramid root dimensions: X={root.SizeX} Y={root.SizeY} Z={root.SizeZ} C={root.SizeC} T={root.SizeT}.");
 
            int bitsPerSample = DetermineSourceBitsPerSample(root);
            var sourcePixelFormat = DetermineSourcePixelFormat(root);
            bool sourceIsInterleavedRgb = IsInterleavedRgbFormat(sourcePixelFormat);
            int sourceChannelCount = sourceIsInterleavedRgb ? BioImage.GetBands(sourcePixelFormat) : 1;
            bool sourceIsBGRA = IsBGRAFormat(sourcePixelFormat);
            int bytesPerSample = bitsPerSample / 8;
            int tileW = 512;
            int tileH = 512;
 
            BioImage.Progress = 0;
            BioImage.Status = "Preparing pyramid Zarr writer";
 
            var levelDescriptors = new List<ResolutionLevelDescriptor>();
            int lastSizeX = int.MaxValue;
            int lastSizeY = int.MaxValue;
            bool haveLast = false;
            var basePixelFormat = DetermineSourcePixelFormat(root);
 
            for (int lvl = 0; lvl < levels.Length; lvl++)
            {
                BioImage levelImage = levels[lvl];
                if (levelImage == null)
                    continue;
 
                int levelWidth =
                    levelImage.Resolutions.Count > 0 && levelImage.Resolutions[0].SizeX > 0
                        ? levelImage.Resolutions[0].SizeX
                        : levelImage.SizeX;
                int levelHeight =
                    levelImage.Resolutions.Count > 0 && levelImage.Resolutions[0].SizeY > 0
                        ? levelImage.Resolutions[0].SizeY
                        : levelImage.SizeY;
                if (levelWidth <= 0 || levelHeight <= 0)
                    continue;
 
                var levelPixelFormat = DetermineSourcePixelFormat(levelImage);
                if (haveLast && levelPixelFormat != basePixelFormat)
                    break;
 
                if (haveLast && (levelWidth > lastSizeX || levelHeight > lastSizeY))
                    break;
 
                if (haveLast && levelWidth == lastSizeX && levelHeight == lastSizeY)
                    continue;
 
                double dsample = root.SizeX > 0 ? (double)root.SizeX / levelWidth : 1.0;
                if (!double.IsFinite(dsample) || dsample <= 0)
                    dsample = 1.0;
 
                levelDescriptors.Add(new ResolutionLevelDescriptor(levelWidth, levelHeight, dsample));
                Log($"[SaveZarr] level={lvl} size={levelWidth}x{levelHeight} downsample={dsample} fmt={levelPixelFormat}");
                lastSizeX = levelWidth;
                lastSizeY = levelHeight;
                haveLast = true;
            }
 
            if (levelDescriptors.Count == 0)
                levelDescriptors.Add(new ResolutionLevelDescriptor(root.SizeX, root.SizeY, 1.0));
 
            // Fallback: if there is somehow no Resolutions list, use the image dims.
            var coord = new ZarrNET.Core.ZCT(root.SizeZ, root.SizeC, root.SizeT);
            var baseDescriptor = new BioImageDescriptor(root.SizeX, root.SizeY, coord)
            {
                Name = Path.GetFileNameWithoutExtension(root.Filename),
                DataType = MapDataType(bitsPerSample),
                PhysicalSizeX = root.PhysicalSizeX,
                PhysicalSizeY = root.PhysicalSizeY,
                PhysicalSizeZ = root.PhysicalSizeZ,
                ChunkY = tileH,
                ChunkX = tileW,
            };
 
            var writer = await OmeZarrWriter.CreateAsync(outputDir, baseDescriptor, levelDescriptors).ConfigureAwait(false);
            try
            {
                long totalPlanes = Math.Max(1L, (long)levelDescriptors.Count * root.SizeT * root.SizeZ * root.SizeC);
                long writtenPlanes = 0;
 
                for (int levelIndex = 0; levelIndex < levels.Length; levelIndex++)
                {
                    BioImage levelImage = levels[levelIndex];
                    if (levelImage == null)
                        continue;
 
                    ResolutionLevelDescriptor lvlDesc = levelDescriptors[Math.Min(levelIndex, levelDescriptors.Count - 1)];
                    int levelBitsPerSample = DetermineSourceBitsPerSample(levelImage);
                    int levelBytesPerSample = levelBitsPerSample / 8;
                    var levelPixelFormat = DetermineSourcePixelFormat(levelImage);
                    bool levelIsInterleavedRgb = IsInterleavedRgbFormat(levelPixelFormat);
                    int levelChannelCount = levelIsInterleavedRgb ? BioImage.GetBands(levelPixelFormat) : 1;
                    bool levelIsBGRA = IsBGRAFormat(levelPixelFormat);
 
                    BioImage.Status = $"Writing pyramid level {levelIndex + 1}/{levels.Length}";
 
                    for (int t = 0; t < levelImage.SizeT; t++)
                    {
                        for (int z = 0; z < levelImage.SizeZ; z++)
                        {
                            for (int c = 0; c < levelImage.SizeC; c++)
                            {
                                if (levelIsInterleavedRgb)
                                {
                                    await WritePlaneInTiles(
                                        writer, levelImage, lvlDesc,
                                        t, c, z,
                                        levelBytesPerSample, tileW, tileH,
                                        levelIndex: levelIndex,
                                        rgbChannelIndex: c,
                                        srcChannelCount: levelChannelCount,
                                        isBGRA: levelIsBGRA,
                                        logicalC: 0).ConfigureAwait(false);
                                }
                                else
                                {
                                    // Pyramid results are full-frame level images. Their
                                    // PyramidalOrigin reflects viewport state, not where the
                                    // level pixels should be placed in the output pyramid.
                                    int originX = 0;
                                    int originY = 0;
 
                                    await WritePlaneFromBuffer(
                                        writer, levelImage, lvlDesc,
                                        t, c, z,
                                        levelBytesPerSample, tileW, tileH,
                                        levelIndex: levelIndex,
                                        originX: originX,
                                        originY: originY,
                                        sourceLevelIndex: 0).ConfigureAwait(false);
                                }
 
                                writtenPlanes++;
                                BioImage.Progress = (float)(writtenPlanes * 100.0 / totalPlanes);
                            }
                        }
                    }
                }
            }
            finally
            {
                try
                {
                    await writer.DisposeAsync().ConfigureAwait(false);
                }
                catch
                {
                }
            }
 
            Recorder.Record($"Zarr.SavePyramidalZarr(new BioImage[] {{ {string.Join(", ", levels.Select(level => level.ToString()))} }}, \"{outputDir}\");");
            BioImage.Progress = 100;
        }

SaveROIs()

static void BioLib.Zarr.SaveROIs ( BioImage b, string outputDir )

static

Writes all annotations on b as a JSON sidecar file at <outputDir>/rois.json.

Call this after SaveZarr so that both image data and ROIs live in the same directory and can be round-tripped together.

        {
            var dtos = new List<RoiDto>(b.Annotations.Count);
 
            foreach (ROI an in b.Annotations)
            {
                // Encode points as "x,y x,y …" (invariant culture) — same
                // format used by BioImage.ROIToString / stringToPoints.
                PointD[] pts  = an.GetPoints();
                var      ptSb = new System.Text.StringBuilder();
                for (int i = 0; i < pts.Length; i++)
                {
                    if (i > 0) ptSb.Append(' ');
                    ptSb.Append(pts[i].X.ToString(CultureInfo.InvariantCulture));
                    ptSb.Append(',');
                    ptSb.Append(pts[i].Y.ToString(CultureInfo.InvariantCulture));
                }
 
                dtos.Add(new RoiDto
                {
                    RoiId       = an.roiID,
                    RoiName     = an.roiName,
                    Type        = an.type.ToString(),
                    Id          = an.id,
                    ShapeIndex  = an.shapeIndex,
                    Text        = an.Text,
                    Serie       = an.serie,
                    Z           = an.coord.Z,
                    C           = an.coord.C,
                    T           = an.coord.T,
                    X           = an.X,
                    Y           = an.Y,
                    W           = an.W,
                    H           = an.H,
                    Points      = ptSb.ToString(),
                    StrokeColor = $"{an.strokeColor.A},{an.strokeColor.R},{an.strokeColor.G},{an.strokeColor.B}",
                    StrokeWidth = an.strokeWidth,
                    FillColor   = $"{an.fillColor.A},{an.fillColor.R},{an.fillColor.G},{an.fillColor.B}",
                    FontSize    = an.fontSize,
                });
            }
 
            var opts = new JsonSerializerOptions { WriteIndented = true };
            string json = JsonSerializer.Serialize(dtos, opts);
            File.WriteAllText(Path.Combine(outputDir, RoiFileName), json);
 
            Recorder.Record($"Zarr.SaveROIs({b}, \"{outputDir}\");");
        }

SaveZarr()

static async void BioLib.Zarr.SaveZarr ( BioImage b, string outputDir )

static

Saves the full 5D content of a BioImage as an OME-Zarr v3 dataset at outputDir . All pyramid resolution levels in b.Resolutions are written.

        {
            // ------------------------------------------------------------------
            // 1. Resolve dimensions and data type from the BioImage
            // ------------------------------------------------------------------
 
            // Guard against zero-size dimensions which cause ZarrNET to throw
            // "regionStart[0] = 0 is out of bounds [0, 0)".
            if (b.SizeX <= 0 || b.SizeY <= 0 || b.SizeZ <= 0 || b.SizeC <= 0 || b.SizeT <= 0)
                throw new InvalidOperationException(
                    $"BioImage has invalid dimensions: X={b.SizeX} Y={b.SizeY} Z={b.SizeZ} C={b.SizeC} T={b.SizeT}. " +
                    "Ensure the image is fully loaded before saving as Zarr.");
 
            // Derive the saved scalar bit depth from BioImage metadata instead of
            // the current display buffer.  The display buffer may be 8-bit even
            // when the source image is 16-bit, which would incorrectly write the
            // Zarr as uint8 and make it appear nearly black on reopen.
            int bitsPerSample = DetermineSourceBitsPerSample(b);
            var sourcePixelFormat = DetermineSourcePixelFormat(b);
            bool sourceIsInterleavedRgb = IsInterleavedRgbFormat(sourcePixelFormat);
            int sourceChannelCount = sourceIsInterleavedRgb ? BioImage.GetBands(sourcePixelFormat) : 1;
            bool sourceIsBGRA = IsBGRAFormat(sourcePixelFormat);
            int exportChannelCount = sourceIsInterleavedRgb && b.SizeC == 1
                ? Math.Min(3, sourceChannelCount)
                : b.SizeC;
 
            var bytesPerSample = bitsPerSample / 8;
            var zarrDataType   = MapDataType(bitsPerSample);
            var totalChannels  = exportChannelCount;
 
            int tileW = 512;
            int tileH = 512;
 
            s_debugTileLogs = 0;
            Log($"[SaveZarr] file={b.Filename} out={outputDir} size={b.SizeX}x{b.SizeY} zct={b.SizeZ}/{b.SizeC}/{b.SizeT} " +
                $"bits={bitsPerSample} bytesPerSample={bytesPerSample} srcPixFmt={sourcePixelFormat} " +
                $"rgb={sourceIsInterleavedRgb} bands={sourceChannelCount}");
            BioImage.Progress = 0;
            BioImage.Status = "Preparing Zarr writer";
 
            // ------------------------------------------------------------------
            // 2. Build per-level descriptors from b.Resolutions
            //    Level 0 is always the full-resolution image (b.SizeX / b.SizeY).
            //    Subsequent levels are taken directly from b.Resolutions[1..N].
            // ------------------------------------------------------------------
 
            var levelDescriptors = new List<ResolutionLevelDescriptor>();
            int lastSizeX = int.MaxValue;
            int lastSizeY = int.MaxValue;
            bool haveLast = false;
            var basePixelFormat = b.Resolutions.Count > 0 ? b.Resolutions[0].PixelFormat : DetermineSourcePixelFormat(b);
 
            for (int lvl = 0; lvl < b.Resolutions.Count; lvl++)
            {
                var res = b.Resolutions[lvl];
                if (res.SizeX <= 0 || res.SizeY <= 0)
                    continue;
 
                if (haveLast && res.PixelFormat != basePixelFormat)
                    break;
 
                if (haveLast && (res.SizeX > lastSizeX || res.SizeY > lastSizeY))
                    break;
 
                if (haveLast && res.SizeX == lastSizeX && res.SizeY == lastSizeY)
                    continue;
 
                double dsample = b.GetLevelDownsample(lvl);
                if (!double.IsFinite(dsample) || dsample <= 0)
                    dsample = 1.0;
 
                levelDescriptors.Add(new ResolutionLevelDescriptor(res.SizeX, res.SizeY, dsample));
                Log($"[SaveZarr] level={lvl} size={res.SizeX}x{res.SizeY} downsample={dsample} fmt={res.PixelFormat}");
                lastSizeX = res.SizeX;
                lastSizeY = res.SizeY;
                haveLast = true;
            }
 
            // Fallback: if there is somehow no Resolutions list, use the image dims.
            var coord = new ZarrNET.Core.ZCT(b.SizeZ, totalChannels, b.SizeT);
 
            var baseDescriptor = new BioImageDescriptor(b.SizeX, b.SizeY, coord)
            {
                Name          = Path.GetFileNameWithoutExtension(b.Filename),
                DataType      = zarrDataType,
                PhysicalSizeX = b.PhysicalSizeX,
                PhysicalSizeY = b.PhysicalSizeY,
                PhysicalSizeZ = b.PhysicalSizeZ,
                ChunkY        = tileH,
                ChunkX        = tileW,
            };
 
            // ------------------------------------------------------------------
            // 4. Create the writer (bootstraps zarr.json metadata on disk for
            //    all levels at once)
            // ------------------------------------------------------------------
 
            var writer = OmeZarrWriter.CreateAsync(outputDir, baseDescriptor, levelDescriptors).Result;
 
            try
            {
                // ------------------------------------------------------------------
                // 5. Stream tiles into each resolution level
                // ------------------------------------------------------------------
                long totalPlanes = Math.Max(1L, (long)levelDescriptors.Count * b.SizeT * b.SizeZ * b.SizeC);
                long writtenPlanes = 0;
 
                for (int levelIndex = 0; levelIndex < levelDescriptors.Count; levelIndex++)
                {
                    var lvlDesc = levelDescriptors[levelIndex];
                    BioImage.Status = $"Writing resolution level {levelIndex + 1}/{levelDescriptors.Count}";
 
                    for (int t = 0; t < b.SizeT; t++)
                    {
                        for (int z = 0; z < b.SizeZ; z++)
                        {
                            for (int c = 0; c < exportChannelCount; c++)
                            {
                                BioImage.Status = $"Writing level {levelIndex + 1}/{levelDescriptors.Count} plane T{t + 1}/{b.SizeT} Z{z + 1}/{b.SizeZ} C{c + 1}/{b.SizeC}";
                                if (sourceIsInterleavedRgb)
                                {
                                    await WritePlaneInTiles(
                                        writer, b, lvlDesc,
                                        t, c, z,
                                        bytesPerSample, tileW, tileH,
                                        levelIndex: levelIndex,
                                        rgbChannelIndex: c,
                                        srcChannelCount: sourceChannelCount,
                                        isBGRA: sourceIsBGRA,
                                        logicalC: 0);
                                }
                                else
                                {
                                    await WritePlaneInTiles(
                                        writer, b, lvlDesc,
                                        t, c, z,
                                        bytesPerSample, tileW, tileH,
                                        levelIndex: levelIndex);
                                }
 
                                writtenPlanes++;
                                BioImage.Progress = (float)(writtenPlanes * 100.0 / totalPlanes);
                            }
                        }
                    }
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
            }
 
            try
            {
                BioImage.Status = "Verifying saved Zarr";
                PostSaveReadback(outputDir).GetAwaiter().GetResult();
            }
            catch (Exception e)
            {
                Log($"[PostSaveReadback] EXCEPTION: {e.GetType().Name}: {e.Message}");
            }
 
            Recorder.Record($"Zarr.SaveZarr({b}, \"{outputDir}\");");
            BioImage.Progress = 100;
        }

Member Data Documentation

RoiFileName

const string BioLib.Zarr.RoiFileName = "rois.json"

static

The file name used for the ROI sidecar that sits beside the Zarr dataset.

---

The documentation for this class was generated from the following file:

• BioLib/Source/Zarr.cs