Interface ISharedImageContext

Namespace: NT2I.ONNX.Abstractions.Interfaces.Hub

Assembly: NT2I.ONNX.Abstractions.dll

Contexte représentant la durée de vie d'une (ou d'un batch de) image(s) source partagée(s) entre plusieurs modèles ONNX d'une même frame.

Le contexte se charge :

D'uploader une seule fois l'image vers la mémoire cible (VRAM en mode CUDA, RAM en mode CPU).
De fournir à la demande des tenseurs préparés selon des IModelInputRequirements spécifiques (resize + normalisation + layout).
De mutualiser les tenseurs : deux demandes avec des Requirements identiques renvoient le même ISharedTensorHandle.
De libérer toutes les ressources (CPU/GPU) au Dispose().

Ce contrat couvre à la fois les usages mono-frame (création/destruction par appel) et pipeline vidéo (instance réutilisée entre frames via LoadFrame(byte[], int, int) / LoadFrames(byte[][], int[], int[])).

public interface ISharedImageContext : IDisposable

Inherited Members: IDisposable.Dispose()

Properties

Device

Périphérique sur lequel le contexte stocke ses tenseurs (déduit du majoritaire des modèles enregistrés au Hub ou imposé explicitement). Pour la v1, DirectML est traité comme CPU.

DataHandlingDeviceEnum Device { get; }

Property Value

DataHandlingDeviceEnum

ImageCount

Nombre d'images sources contenues dans le contexte.

1 pour un contexte mono-image (cas mono-frame).
N pour un contexte batch multi-image (N images distinctes uploadées indépendamment).

Pour qu'un appel à GetTensor(IModelInputRequirements) réussisse, il faut que requirements.BatchSize == ImageCount. Tout autre cas lève une InvalidOperationException.

int ImageCount { get; }

Property Value

int

OriginalSize

Taille (largeur × hauteur) de la première image source brute, en pixels. Permet aux post-processeurs de réaliser un re-scaling inverse (ex. dénormalisation des bounding boxes YOLO). Pour un contexte multi-image, chaque image peut avoir une taille différente — utilisez GetOriginalSize(int) pour récupérer la taille d'une image spécifique du batch.

ImageSize OriginalSize { get; }

Property Value

ImageSize

Methods

GetOriginalSize(int)

Taille (largeur × hauteur) de l'image source à l'index imageIndex. Utilisé pour les batchs hétérogènes où chaque image peut avoir des dimensions distinctes (cas vidéo avec crops, ou frames de résolutions différentes).

ImageSize GetOriginalSize(int imageIndex)

Parameters

imageIndex int: Index dans le batch, 0 ≤ imageIndex < ImageCount.

Returns

ImageSize

Exceptions

ArgumentOutOfRangeException: Si l'index est hors bornes.

GetTensor(IModelInputRequirements)

Récupère (ou construit à la demande, puis cache) un tenseur pré-traité satisfaisant les besoins fournis. Le handle retourné est refcompté : si plusieurs modèles ont les mêmes requirements, ils partagent la même instance.

Le consommateur doit appeler Dispose() sur le handle quand il n'en a plus besoin pour permettre au contexte de libérer la mémoire au moment opportun.

ISharedTensorHandle GetTensor(IModelInputRequirements requirements)

Parameters

requirements IModelInputRequirements: Besoins déclaratifs du modèle (taille, normalisation, géométrie, batch).

Returns

ISharedTensorHandle: Un handle partagé sur le tenseur préparé.

Exceptions

ArgumentNullException: Si requirements est null.
ObjectDisposedException: Si le contexte a déjà été disposé.

LoadFrame(byte[], int, int)

Recharge l'image source mono-image. Réutilise les buffers existants (RAM ou VRAM) si les dimensions sont identiques à la frame précédente — typique d'un pipeline vidéo / ligne de production. Invalide systématiquement le cache de tenseurs preprocessés (les pixels ont changé).

Le caller doit ensuite re-binder les modèles enregistrés via SharedImageCoordinator.RebindAll(ctx) pour qu'ils récupèrent le nouveau tenseur.

void LoadFrame(byte[] bgrPackedImage, int width, int height)

Parameters

bgrPackedImage byte[]: Nouvelle image BGR packed.
width int: Largeur de la nouvelle image.
height int: Hauteur de la nouvelle image.

Exceptions

ArgumentNullException: Si bgrPackedImage est null.
ObjectDisposedException: Si le contexte a déjà été disposé.
InvalidOperationException: Si le contexte a été créé en multi-image (ImageCount > 1). Utiliser LoadFrames(byte[][], int[], int[]) dans ce cas.

LoadFrames(byte[][], int[], int[])

Recharge un batch d'images sources. Réutilise les buffers existants si les dimensions de chaque slot sont inchangées. Invalide le cache de tenseurs preprocessés.

void LoadFrames(byte[][] bgrPackedImages, int[] widths, int[] heights)

Parameters

bgrPackedImages byte[][]: Tableau de N images BGR packed.
widths int[]: Largeurs des N images (longueur N).
heights int[]: Hauteurs des N images (longueur N).

Exceptions

ArgumentNullException: Si l'un des arguments est null.
ArgumentException: Si la longueur de bgrPackedImages diffère de ImageCount (le contexte ne supporte pas le redimensionnement de la taille de batch).
ObjectDisposedException: Si le contexte a déjà été disposé.