/// <summary>
/// Get the NULL-terminated array of associated image names.
/// Certain vendor-specific associated images may exist within a whole slide image. They are encoded as key-value pairs. This call provides a list of names as strings that can be used to read associated images with openslide_get_associated_image_dimensions() and openslide_read_associated_image().
/// </summary>
/// <param name="osr">The OpenSlide object.</param>
/// <returns>A NULL-terminated string array of associated image names, or an empty array if an error occurred.</returns>
public static unsafe string[] GetAssociatedImageNames(OpenSlideImageSafeHandle osr)
{
var list = new List <string>();
IntPtr *pCurrent = (IntPtr *)GetAssociatedImageNames_Internal(osr);
while (*pCurrent != IntPtr.Zero)
{
string?name = StringFromNativeUtf8(*pCurrent);
list.Add(name !);
pCurrent++;
}
return(list.ToArray());
}
/// <summary>
/// Copy pre-multiplied ARGB data from an associated image.
/// This function reads and decompresses an associated image associated with a whole slide image. dest must be a valid pointer to enough memory to hold the image, at least (width * height * 4) bytes in length. Get the width and height with openslide_get_associated_image_dimensions(). This call does nothing if an error occurred.
/// </summary>
/// <param name="osr">The OpenSlide object. </param>
/// <param name="name">The name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().</param>
/// <param name="dest">The destination buffer for the ARGB data.</param>
public static unsafe void ReadAssociatedImage(OpenSlideImageSafeHandle osr, string name, void *dest)
{
byte * pointer = stackalloc byte[64];
UnsafeUtf8Encoder utf8Encoder = new UnsafeUtf8Encoder(pointer, 64);
try
{
ReadAssociatedImage_Internal(osr, utf8Encoder.Encode(name), dest);
}
finally
{
utf8Encoder.Dispose();
}
}
/// <summary>
/// Get the value of a single property.
/// Certain vendor-specific metadata properties may exist within a whole slide image. They are encoded as key-value pairs. This call provides the value of the property given by name.
/// </summary>
/// <param name="osr">The OpenSlide object. </param>
/// <param name="utf8Name">The name of the desired property. Must be a valid name as given by openslide_get_property_names().</param>
/// <returns>The value of the named property, or NULL if the property doesn't exist or an error occurred. </returns>
public static unsafe string?GetPropertyValue(OpenSlideImageSafeHandle osr, ReadOnlySpan <byte> utf8Name)
{
if (utf8Name.IsEmpty || utf8Name[utf8Name.Length - 1] != 0)
{
throw new ArgumentException();
}
fixed(byte *pName = utf8Name)
{
IntPtr pResult = GetPropertyValueInternal(osr, (IntPtr)pName);
return(StringFromNativeUtf8(pResult));
}
}
/// <summary>
/// Get the dimensions of an associated image.
/// This function returns the width and height of an associated image associated with a whole slide image. Once the dimensions are known, use openslide_read_associated_image() to read the image.
/// </summary>
/// <param name="osr">The OpenSlide object.</param>
/// <param name="name">The name of the desired associated image. Must be a valid name as given by openslide_get_associated_image_names().</param>
/// <param name="w">The width of the associated image, or -1 if an error occurred.</param>
/// <param name="h">The height of the associated image, or -1 if an error occurred.</param>
public static unsafe void GetAssociatedImageDimensions(OpenSlideImageSafeHandle osr, string name, out long w, out long h)
{
byte * pointer = stackalloc byte[64];
UnsafeUtf8Encoder utf8Encoder = new UnsafeUtf8Encoder(pointer, 64);
try
{
GetAssociatedImageDimensions_Internal(osr, utf8Encoder.Encode(name), out w, out h);
}
finally
{
utf8Encoder.Dispose();
}
}
/// <summary>
/// Get the value of a single property.
/// Certain vendor-specific metadata properties may exist within a whole slide image. They are encoded as key-value pairs. This call provides the value of the property given by name.
/// </summary>
/// <param name="osr">The OpenSlide object. </param>
/// <param name="name">The name of the desired property. Must be a valid name as given by openslide_get_property_names().</param>
/// <returns>The value of the named property, or NULL if the property doesn't exist or an error occurred. </returns>
public static unsafe string?GetPropertyValue(OpenSlideImageSafeHandle osr, string name)
{
byte * pointer = stackalloc byte[64];
UnsafeUtf8Encoder utf8Encoder = new UnsafeUtf8Encoder(pointer, 64);
try
{
IntPtr pResult = GetPropertyValueInternal(osr, utf8Encoder.Encode(name));
return(StringFromNativeUtf8(pResult));
}
finally
{
utf8Encoder.Dispose();
}
}
private static extern void GetAssociatedImageDimensions_Internal(OpenSlideImageSafeHandle osr, IntPtr name, out long w, out long h);
/// <summary> /// Get the dimensions of a level. /// </summary> /// <param name="osr">The OpenSlide object. </param> /// <param name="level">The desired level. </param> /// <param name="w">The width of the image, or -1 if an error occurred or the level was out of range. </param> /// <param name="h">The height of the image, or -1 if an error occurred or the level was out of range. </param> public static void GetLevelDimensions(OpenSlideImageSafeHandle osr, int level, out long w, out long h) => GetLevelDimensionsInternal(osr, level, out w, out h);
private static extern void GetLevelDimensionsInternal(OpenSlideImageSafeHandle osr, int level, out long w, out long h);
/// <summary>
/// Get the current error string.
/// For a given OpenSlide object, once this function returns a non-NULL value, the only useful operation on the object is to call openslide_close() to free its resources.
/// </summary>
/// <param name="osr">The OpenSlide object. </param>
/// <returns>A string describing the original error that caused the problem, or NULL if no error has occurred. </returns>
public static string?GetError(OpenSlideImageSafeHandle osr)
{
IntPtr pResult = GetErrorInternal(osr);
return(StringFromNativeUtf8(pResult));
}
private static unsafe extern void ReadRegionInternal(OpenSlideImageSafeHandle osr, void *dest, long x, long y, int level, long w, long h);
/// <summary> /// Get the best level to use for displaying the given downsample. /// </summary> /// <param name="osr">The OpenSlide object.</param> /// <param name="downsample">The downsample factor.</param> /// <returns>The level identifier, or -1 if an error occurred.</returns> public static int GetBestLevelForDownsample(OpenSlideImageSafeHandle osr, double downsample) => GetBestLevelForDownsampleInternal(osr, downsample);
internal static extern int GetBestLevelForDownsampleInternal(OpenSlideImageSafeHandle osr, double downsample);
/// <summary> /// Get the downsampling factor of a given level. /// </summary> /// <param name="osr">The OpenSlide object.</param> /// <param name="level">The desired level. </param> /// <returns>The downsampling factor for this level, or -1.0 if an error occurred or the level was out of range. </returns> public static double GetLevelDownsample(OpenSlideImageSafeHandle osr, int level) => GetLevelDownsampleInternal(osr, level);
private static extern double GetLevelDownsampleInternal(OpenSlideImageSafeHandle osr, int level);
private static extern IntPtr GetPropertyNamesInternal(OpenSlideImageSafeHandle osr);
/// <summary> /// Copy pre-multiplied ARGB data from a whole slide image. /// This function reads and decompresses a region of a whole slide image into the specified memory location. dest must be a valid pointer to enough memory to hold the region, at least (w * h * 4) bytes in length. If an error occurs or has occurred, then the memory pointed to by dest will be cleared. /// </summary> /// <param name="osr">The OpenSlide object. </param> /// <param name="dest">The destination buffer for the ARGB data. </param> /// <param name="x">The top left x-coordinate, in the level 0 reference frame. </param> /// <param name="y">The top left y-coordinate, in the level 0 reference frame. </param> /// <param name="level">The desired level. </param> /// <param name="w">The width of the region. Must be non-negative. </param> /// <param name="h">The height of the region. Must be non-negative. </param> public static unsafe void ReadRegion(OpenSlideImageSafeHandle osr, void *dest, long x, long y, int level, long w, long h) => ReadRegionInternal(osr, dest, x, y, level, w, h);
private static unsafe extern void ReadAssociatedImage_Internal(OpenSlideImageSafeHandle osr, IntPtr name, void *dest);
private static extern int GetLevelCountInternal(OpenSlideImageSafeHandle osr);
private static extern IntPtr GetAssociatedImageNames_Internal(OpenSlideImageSafeHandle osr);
/// <summary> /// Get the number of levels in the whole slide image. /// </summary> /// <param name="osr">The OpenSlide object. </param> /// <returns>The number of levels, or -1 if an error occurred. </returns> public static int GetLevelCount(OpenSlideImageSafeHandle osr) => GetLevelCountInternal(osr);
private static extern IntPtr GetErrorInternal(OpenSlideImageSafeHandle osr);
private static extern IntPtr GetPropertyValueInternal(OpenSlideImageSafeHandle osr, IntPtr name);
