BioLib.SlideImage Class Reference

openslide wrapper More...

Inheritance diagram for BioLib.SlideImage:

Public Member Functions
	SlideImage ()
ImageDimension	GetLevelDimension (int level)
IEnumerable< ImageDimension >	GetLevelDimensions ()
	Get all level dimensions.
void	ResetDimensionsCache ()
	Clears the cached level-0 dimensions so Dimensions is re-derived from the active well field on the next access. Call this whenever BioImage.WellIndex changes for a well image.
unsafe byte[]	ReadRegion (int level, ZCT zct, long x, long y, long width, long height)
	Copy pre-multiplied BGRA data from a whole slide image.
bool	TryReadRegion (int level, long x, long y, long width, long height, out byte[] data, ZCT zct)
	Copy pre-multiplied BGRA data from a whole slide image.
async Task< byte[]>	TryReadRegionAsync (int level, long x, long y, long width, long height, ZCT zct, CancellationToken ct=default)
	Copy pre-multiplied BGRA data from a whole slide image.
void	Close ()
void	Dispose ()
async Task< byte[]>	ReadRegionAsync (int level, long curLevelOffsetXPixel, long curLevelOffsetYPixel, int curTileWidth, int curTileHeight, ZCT coord, CancellationToken ct=default)

Static Public Member Functions
static string	DetectVendor (string filename)
	Quickly determine whether a whole slide image is recognized.
static void	Initialize (string path=null)
	Add .dll directory to PATH.
static SlideImage	Open (BioImage b)
	Open.
static double	CalculateBaseFactor (int originalResolution, int lastLevelResolution, int totalLevels)
	Calculates the base downsampling factor between two levels of a slide.
static List< double >	GetLevelDownsamples (double baseDownsampleFactor, int totalLevels)
	Calculates the downsample factors for each level of a slide.

Protected Member Functions
virtual void	Dispose (bool disposing)
	Dispose.

Properties
BioImage	BioImage [get, set]
int	LevelCount [get]
	Get the number of levels in the whole slide image.
ImageDimension	Dimensions [get]

Detailed Description

openslide wrapper

Constructor & Destructor Documentation

SlideImage()

BioLib.SlideImage.SlideImage

(

)

Parameters

handle
isOwner	close handle when disposed

Exceptions

OpenSlideException

        {
            
        }

Member Function Documentation

CalculateBaseFactor()

static double BioLib.SlideImage.CalculateBaseFactor ( int originalResolution, int lastLevelResolution, int totalLevels )

static

Calculates the base downsampling factor between two levels of a slide.

Parameters

originalDimension	The dimension (width or height) of the original level.
nextLevelDimension	The dimension (width or height) of the next level.

Returns

The base downsampling factor.

        {
            if (totalLevels <= 1)
            {
                throw new ArgumentException("Total levels must be greater than 1 to calculate a base factor.");
            }
            if (lastLevelResolution <= 0 || originalResolution <= 0)
            {
                throw new ArgumentException("Resolutions must be greater than 0.");
            }
 
            // Calculate the base downsampling factor
            double baseFactor = Math.Pow((double)originalResolution / lastLevelResolution, 1.0 / (totalLevels - 1));
            return baseFactor;
        }

Close()

void BioLib.SlideImage.Close

(

)

        {
           
        }

DetectVendor()

static string BioLib.SlideImage.DetectVendor ( string filename )

static

Quickly determine whether a whole slide image is recognized.

If OpenSlide recognizes the file referenced by filename , return a string identifying the slide format vendor.This is equivalent to the value of the NativeMethods.VENDOR property. Calling Open(string) on this file will return a valid OpenSlide object or an OpenSlide object in error state.

Otherwise, return null.Calling Open(string) on this file will also return null.

Parameters

filename

The filename to check. On Windows, this must be in UTF-8.

Returns

An identification of the format vendor for this file, or NULL.

        {
            return filename;
        }

Dispose() [1/2]

void BioLib.SlideImage.Dispose

(

)

        {
            Dispose(disposing: true);
            GC.SuppressFinalize(this);
        }

Dispose() [2/2]

virtual void BioLib.SlideImage.Dispose ( bool disposing )

protectedvirtual

Dispose.

Parameters

disposing

        {
            if (!disposedValue)
            {
                if (disposing)
                {
                }
 
                Close();
                disposedValue = true;
            }
        }

GetLevelDimension()

ImageDimension BioLib.SlideImage.GetLevelDimension

(

int

level

)

        {
            // For well-plate fields, derive dimensions from the field's pyramid shape.
            if (BioImage.Type == BioImage.ImageType.well &&
                BioImage.ZarrWellLevels?.Count > 0)
            {
                int fi = Math.Clamp(BioImage.WellIndex, 0, BioImage.ZarrWellLevels.Count - 1);
                var fieldLevels = BioImage.ZarrWellLevels[fi];
                if (fieldLevels != null && fieldLevels.Count > 0)
                {
                    int lev   = Math.Clamp(level, 0, fieldLevels.Count - 1);
                    var shape = fieldLevels[lev].Shape;
                    var axes  = fieldLevels[lev].EffectiveAxes;
                    int w = 1, h = 1;
                    for (int i = 0; i < axes.Length; i++)
                    {
                        switch (axes[i].Name.ToLowerInvariant())
                        {
                            case "x": w = (int)shape[i]; break;
                            case "y": h = (int)shape[i]; break;
                        }
                    }
                    return new ImageDimension(w, h);
                }
            }
            return new ImageDimension(BioImage.Resolutions[level].SizeX, BioImage.Resolutions[level].SizeY);
        }

GetLevelDimensions()

IEnumerable< ImageDimension > BioLib.SlideImage.GetLevelDimensions

(

)

Get all level dimensions.

Returns

Exceptions

OpenSlideException

        {
            var count = LevelCount;
            for (int i = 0; i < count; i++)
            {
                yield return GetLevelDimension(i);
            }
        }

GetLevelDownsamples()

static List< double > BioLib.SlideImage.GetLevelDownsamples ( double baseDownsampleFactor, int totalLevels )

static

Calculates the downsample factors for each level of a slide.

Parameters

baseDownsampleFactor	The downsample factor between each level.
totalLevels	Total number of levels in the slide.

Returns

A list of downsample factors for each level.

        {
            var levelDownsamples = new List<double>();
 
            for (int level = 0; level < totalLevels; level++)
            {
                // Calculate the downsample factor for the current level.
                // Math.Pow is used to raise the baseDownsampleFactor to the power of the level.
                double downsampleFactorAtLevel = Math.Pow(baseDownsampleFactor, level);
                levelDownsamples.Add(downsampleFactorAtLevel);
            }
 
            return levelDownsamples;
        }

Initialize()

static void BioLib.SlideImage.Initialize ( string path = null )

static

Add .dll directory to PATH.

Parameters

path

Exceptions

OpenSlideException

        {
            
        }

Open()

static SlideImage BioLib.SlideImage.Open ( BioImage b )

static

Open.

Parameters

filename

Returns

Exceptions

OpenSlideException

        {
            SlideImage im = new SlideImage();
            im.BioImage = b;
            return im;
        }

ReadRegion()

unsafe byte[] BioLib.SlideImage.ReadRegion	(	int	level,
		ZCT	zct,
		long	x,
		long	y,
		long	width,
		long	height )

Copy pre-multiplied BGRA data from a whole slide image.

Parameters

level	The desired level.
x	The top left x-coordinate, in the level 0 reference frame.
y	The top left y-coordinate, in the level 0 reference frame.
width	The width of the region. Must be non-negative.
height	The height of the region. Must be non-negative.

Returns

The pixel data of this region.

Exceptions

ArgumentOutOfRangeException

Exceptions OpenSlideException

        {
            try
            {
                var tile = BioImage.GetTile(
                    BioImage.GetFrameIndex(zct.Z, zct.C, zct.T),
                    level,
                    (int)x,
                    (int)y,
                    (int)width,
                    (int)height).Result;
                if (tile == null)
                    return null;
 
                var bytes = tile.Bytes;
                tile.Dispose();
                return bytes;
            }
            catch (Exception e)
            {
                if (BioImage == null)
                    Console.WriteLine("BioImage is null. ");
                Console.WriteLine(e.Message + " " + e.StackTrace);
            }
            return null;
        }

ReadRegionAsync()

async Task< byte[]> BioLib.SlideImage.ReadRegionAsync	(	int	level,
		long	curLevelOffsetXPixel,
		long	curLevelOffsetYPixel,
		int	curTileWidth,
		int	curTileHeight,
		ZCT	coord,
		CancellationToken	ct = default )

        {
            try
            {
                byte[] bts = await TryReadRegionAsync(level, curLevelOffsetXPixel, curLevelOffsetYPixel, curTileWidth, curTileHeight, coord, ct);
                return bts;
            }
            catch (Exception e)
            {
                return null;
            }
        }

ResetDimensionsCache()

void BioLib.SlideImage.ResetDimensionsCache

(

)

Clears the cached level-0 dimensions so Dimensions is re-derived from the active well field on the next access. Call this whenever BioImage.WellIndex changes for a well image.

TryReadRegion()

bool BioLib.SlideImage.TryReadRegion	(	int	level,
		long	x,
		long	y,
		long	width,
		long	height,
		out byte[]	data,
		ZCT	zct )

Copy pre-multiplied BGRA data from a whole slide image.

Parameters

level	The desired level.
x	The top left x-coordinate, in the level 0 reference frame.
y	The top left y-coordinate, in the level 0 reference frame.
width	The width of the region. Must be non-negative.
height	The height of the region. Must be non-negative.
data	The BGRA pixel data of this region.

Returns

        {
            var tile = BioImage.GetTile(
                BioImage.GetFrameIndex(zct.Z, zct.C, zct.T),
                level,
                (int)x,
                (int)y,
                (int)width,
                (int)height).Result;
            if (tile == null)
            {
                data = null;
                return false;
            }
 
            data = tile.Bytes;
            tile.Dispose();
            if (data == null)
                return false;
            else
                return true;
        }

TryReadRegionAsync()

async Task< byte[]> BioLib.SlideImage.TryReadRegionAsync	(	int	level,
		long	x,
		long	y,
		long	width,
		long	height,
		ZCT	zct,
		CancellationToken	ct = default )

Copy pre-multiplied BGRA data from a whole slide image.

Parameters

level	The desired level.
x	The top left x-coordinate, in the level 0 reference frame.
y	The top left y-coordinate, in the level 0 reference frame.
width	The width of the region. Must be non-negative.
height	The height of the region. Must be non-negative.
data	The BGRA pixel data of this region.

Returns

summary> Close an OpenSlide object. /summary> remarks> No other threads may be using the object. After this call returns, the object cannot be used anymore. /remarks>

Property Documentation

BioImage

BioImage BioLib.SlideImage.BioImage

getset

{ get; set; }

Dimensions

ImageDimension BioLib.SlideImage.Dimensions

get

        {
            get
            {
                if (_dimensionsRef == null)
                {
                    lock (_dimensionsSynclock)
                    {
                        if (_dimensionsRef == null)
                            _dimensionsRef = GetLevelDimension(0);
                    }
                }
                return _dimensionsRef.Value;
            }
        }

LevelCount

int BioLib.SlideImage.LevelCount

get

Get the number of levels in the whole slide image.

<return>The number of levels, or -1 if an error occurred.</return>

Exceptions

OpenSlideException

        {
            get
            {
                // For well-plate fields use the active field's pyramid level count.
                if (BioImage.Type == BioImage.ImageType.well &&
                    BioImage.ZarrWellLevels?.Count > 0)
                {
                    int fi = Math.Clamp(BioImage.WellIndex, 0, BioImage.ZarrWellLevels.Count - 1);
                    return BioImage.ZarrWellLevels[fi]?.Count ?? 1;
                }
                if (BioImage.MacroResolution.HasValue)
                    return BioImage.Resolutions.Count - 2;
                return BioImage.Resolutions.Count;
            }
        }

---

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

• BioLib/Source/Bio/SlideImage.cs