Class CpuSharedImageContext

Namespace: NT2I.ONNX.Hub

Assembly: NT2I.ONNX.Hub.dll

Contexte d'image partagée sur chemin CPU.

Stocke une (mono-image) ou plusieurs (batch multi-image) images BGR brutes une seule fois, puis matérialise à la demande des tenseurs pré-traités selon les IModelInputRequirements fournis par chaque modèle. Les tenseurs sont mis en cache : deux modèles avec des requirements identiques partagent le même buffer float[].

Pipeline de pré-traitement (par image source) :

Démultiplexage BGR entrelacé → canaux R, G, B séparés.
Transformation géométrique par canal (Letterbox ou StretchResize).
Assemblage planaire [R plane | G plane | B plane].
Normalisation (Scale01 ou ImageNet mean/std).

En batch multi-image, les N images sont prétraitées indépendamment et concaténées dans le tenseur de sortie au layout [N, C, H, W]. Les tailles d'entrée sont hétérogènes (chaque image peut avoir ses propres width/height) ; toutes les sorties partagent la taille cible imposée par Requirements.

Strict-match BatchSize : requirements.BatchSize doit être égal au nombre d'images stockées dans le contexte (ImageCount). Toute incohérence lève une InvalidOperationException — pas de réplication automatique.

public sealed class CpuSharedImageContext : ISharedImageContext, IDisposable

Inheritance: object

CpuSharedImageContext

Implements: ISharedImageContext

IDisposable

Inherited Members: object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

CpuSharedImageContext(byte[], int, int)

Crée un contexte mono-image à partir d'une seule image BGR entrelacée. Le buffer est copié en interne pour garantir la stabilité de la durée de vie. Equivalent à un contexte multi-image avec N=1.

public CpuSharedImageContext(byte[] bgrPackedImage, int width, int height)

Parameters

bgrPackedImage byte[]: Image source en format BGR entrelacé (layout OpenCV : B₀G₀R₀ B₁G₁R₁ …).
width int: Largeur de l'image source en pixels (> 0).
height int: Hauteur de l'image source en pixels (> 0).

Exceptions

ArgumentNullException: Si bgrPackedImage est null.
ArgumentException: Si bgrPackedImage.Length ≠ width × height × 3, ou si width/height ≤ 0.

CpuSharedImageContext(byte[][], int[], int[])

Crée un contexte batch multi-image à partir de N images BGR de tailles potentiellement hétérogènes (chaque image peut avoir ses propres width/height).

public CpuSharedImageContext(byte[][] bgrPackedImages, int[] widths, int[] heights)

Parameters

bgrPackedImages byte[][]: Tableau de N images BGR entrelacées (chaque byte[] = 1 image de longueur w × h × 3).
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 les longueurs des trois tableaux ne correspondent pas, si N=0, ou si l'une des images a une longueur incohérente avec sa taille déclarée.

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.

public 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.

public 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.

public ImageSize OriginalSize { get; }

Property Value

ImageSize

Methods

Dispose()

public void Dispose()

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).

public 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.

public 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é.

Remarks

Le cache garantit qu'un seul tenseur est construit pour des requirements identiques. Le refcount du handle est incrémenté à chaque appel : le consommateur doit appeler Dispose() sur le handle retourné lorsqu'il n'en a plus besoin.

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.

public 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.

public 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é.