Interfacce per filtri di segmentazione
A partire da Windows Vista, WIA supporterà i filtri di segmentazione. Un filtro di segmentazione deve implementare l'interfaccia IWiaSegmentationFilter.
L'interfaccia IWiaSegmentationFilter dipende dalla nuova interfaccia IWiaItem2 (per Windows Vista), usata in questa sezione, è un superset di IWiaItem. Oltre ai metodi IWiaItem , l'interfaccia IWiaItem2 include il metodo IWiaItem2::GetExtension, usato da un'applicazione per creare estensioni WIA, incluso il filtro di segmentazione. Le interfacce IWiaItem e IWiaItem2 sono descritte nella documentazione di Microsoft Windows SDK.
L'interfaccia IWiaSegmentationFilter implementa un singolo metodo , DetectRegions. Questo metodo include tre parametri, lFlags, pInputStream e pWiaItem2.
Il parametro lFlags è attualmente inutilizzato.
Il parametro pInputStream è un puntatore all'immagine in cui eseguire la segmentazione. In genere si tratta di un'immagine di anteprima che rappresenta l'intera superficie di analisi del letto piatto. Il flusso viene creato dall'applicazione nel relativo metodo IWiaTransferCallback::GetNextStream ; questo metodo viene chiamato durante l'acquisizione di immagini. Il driver scrive i dati dell'immagine acquisiti nel flusso restituito dal metodo IWiaTransferCallback::GetNextStream . Questo è anche il flusso che deve essere passato al filtro di segmentazione dall'applicazione. L'interfaccia IWiaTransferCallback è descritta nella documentazione di Windows SDK.
Il parametro pWiaItem2 è un puntatore all'elemento WIA per cui è stato acquisito pInputStream . Viene anche definito elemento padre. Ad esempio, l'elemento che pWiaItem2 punta può essere l'elemento flatbed.
Il metodo IWiaSegmentationFilter::D etectRegions viene usato per determinare le sottoregioni dell'immagine rappresentata da pInputStream. Per ogni sottoregion rilevata, IWiaSegmentationFilter::D etectRegions crea un nuovo elemento WIA figlio nell'elemento a cui punta pWiaItem2. Per ogni elemento figlio, il filtro di segmentazione deve impostare i valori per le proprietà WIA seguenti: WIA_IPS_XPOS, WIA_IPS_YPOS, WIA_IPS_XEXTENT e WIA_IPS_YEXTENT. Queste proprietà rappresentano il rettangolo di selezione dell'area da analizzare. Un filtro di segmentazione più avanzato può anche voler impostare altre proprietà WIA, ad esempio proprietà WIA per filtri di segmentazione se il driver supporta deskewing.
Il diagramma seguente illustra come il filtro di segmentazione modifica l'albero degli elementi dell'applicazione. In questo diagramma, il filtro di segmentazione ha rilevato tre immagini sul letto piatto e, per ogni immagine, ha creato un nuovo elemento figlio sotto l'elemento flatbed.
Un filtro di segmentazione deve supportare tutti i formati di immagine supportati dal driver che estende. Il filtro di segmentazione fornito da Microsoft supporta i formati BMP, GIF, JPEG, PNG e TIFF. Pertanto, qualsiasi driver che usa questo filtro è limitato a questi formati.
Per creare gli elementi figlio, il filtro di segmentazione chiama il metodo IWiaItem2::CreateChildItem . Di seguito è riportato un esempio di tale chiamata:
lItemFlags = WiaItemTypeGenerated | WiaItemTypeTransfer | WiaItemTypeImage | WiaItemTypeFile |
WiaItemTypeProgrammableDataSource;
lCreationFlags = COPY_PARENT_PROPERTY_VALUES;
pWiaItem2->CreateChildItem(lItemFlags,
lCreationFlags,
bstrItemName,
&pChildItem);
IWiaItem2::CreateChildItem differisce leggermente da IWiaItem::CreateChildItem. Il metodo IWiaItem2::CreateChildItem ha un nuovo parametro, lCreationFlags; Il parametro IWiaItem2::CreateChildItem del metodo lItemFlags corrisponde al parametro lFlags di IWiaItem::CreateChildItem. Passando COPY_PARENT_PROPERTY_VALUES con il parametro lCreationFlags al servizio WIA, come illustrato nel frammento di codice precedente, indica al servizio WIA di impostare tutte le proprietà WIA leggibili/scrivibili dell'elemento figlio agli stessi valori del codice padre. Il motivo per cui un filtro di segmentazione deve passare questo flag consiste nel garantire che le proprietà, ad esempio il formato dell'immagine e la risoluzione nell'elemento figlio appena creato, siano l'elemento padre. È importante che la risoluzione sia la stessa perché le proprietà di estensione impostate dal filtro di segmentazione nell'elemento figlio dipendono dalla risoluzione dell'immagine. È anche importante che il formato e la risoluzione dell'immagine siano uguali nell'elemento figlio se un'applicazione vuole usare il componente di anteprima (descritto nella documentazione di Microsoft Windows SDK). Prima di acquisire l'immagine finale, un'applicazione può modificare la risoluzione per acquisire un'immagine di qualità superiore dallo scanner.
È importante notare che il filtro di segmentazione è associato alle stesse restrizioni di un'applicazione in ciò che può e non può eseguire. Ciò significa che un'applicazione può modificare gli elementi figlio creati dal filtro di segmentazione. Ad esempio, un utente potrebbe non essere soddisfatto dell'area rilevata dal filtro di segmentazione e potrebbe indicare all'applicazione di modificare questa area trascinando gli angoli. L'applicazione può anche eliminare gli elementi figlio creati dal filtro di segmentazione e aggiungere nuovi elementi.
Si noti che il filtro di segmentazione non è responsabile della "pulizia" degli elementi figlio creati. Quindi, se l'applicazione chiama IWiaSegmentationFilter::D etectRegions più volte, l'applicazione deve prima eliminare gli elementi figlio creati nella prima chiamata al metodo IWiaSegmentationFilter::D etectRegions . Il filtro di segmentazione non è responsabile anche della reimpostazione del parametro pInputStream . L'applicazione deve assicurarsi che abbia impostato il puntatore di ricerca all'inizio del flusso prima di chiamare il filtro di segmentazione.
Il filtro di segmentazione deve essere usato solo sull'elemento film e sull'elemento flatbed. Per l'analisi del film, uno scanner spesso include fotogrammi fissi, nel qual caso il driver crea gli elementi figlio (per altre informazioni fare riferimento al layout dell'albero degli elementi dello scanner WIA ). In questo caso, un'applicazione non deve richiamare il filtro di segmentazione per il rilevamento dell'area e la creazione di elementi figlio.
Se un driver include un filtro di segmentazione, deve implementare la proprietà WIA_IPS_SEGMENTATION per gli elementi WIA flat e film. Questa proprietà di sola lettura include due valori validi: WIA_USE_SEGMENTATION_FILTER e WIA_DONT_USE_SEGMENTATION_FILTER, che il driver imposta. Questa proprietà consente a un'applicazione di sapere se deve usare il filtro di segmentazione del driver per il rilevamento dell'area in un determinato elemento.
Se uno scanner usa fotogrammi fissi per l'analisi del film, questa proprietà verrà impostata su WIA_DONT_USE_SEGMENTATION_FILTER nell'elemento film. In questo caso, l'applicazione non deve provare a caricare il filtro di segmentazione dopo l'acquisizione dell'anteprima del film; deve invece enumerare gli elementi figlio creati dal driver. Questi elementi figlio rappresentano i fotogrammi fissi.
Poiché un elemento WIA viene passato a IWiaSegmentationFilter::D etectRegions, è possibile che il filtro di segmentazione usi algoritmi diversi a seconda della categoria dell'elemento, ad esempio flat o film. La categoria di un elemento viene archiviata nella proprietà WIA_IPA_ITEM_CATEGORY .
Se un'applicazione modifica le proprietà in pWiaItem2 tra l'acquisizione dell'immagine in pInputStream e la chiamata dell'applicazione a IWiaSegmentationFilter::D etectRegions, è necessario ripristinare le impostazioni delle proprietà originali, ad esempio le impostazioni delle proprietà che l'elemento aveva quando il flusso è stato acquisito. Questa operazione può essere eseguita usando i metodi IWiaPropertyStorage::GetPropertyStream e IWiaPropertyStorage::SetPropertyStream. Il motivo per cui queste modifiche devono essere ripristinate è che potrebbero essere presenti informazioni nell'elemento WIA necessario per il filtro di segmentazione, ma che non è archiviato nell'intestazione dell'immagine. Esempi di tali informazioni sono i dati archiviati nelle proprietà WIA_IPS_XPOS, WIA_IPS_YPOS e WIA_IPS_ROTATION. L'interfaccia IWiaPropertyStorage e i relativi metodi sono descritti nella documentazione di Windows SDK.
Un'applicazione ottiene un'istanza del filtro di segmentazione chiamando IWiaItem2::GetExtension (descritta nella documentazione di Windows SDK). Un'applicazione chiama in genere questo metodo prima di visualizzare la relativa finestra di anteprima. Questo perché un driver potrebbe non essere disponibile con un filtro di segmentazione, in questo caso l'interfaccia utente deve sapere di non visualizzare un pulsante non supportato, ad esempio Esegui segmentazione.