Fotocamera app complementari

Articolo
12/19/2024

Questo articolo descrive le app complementari, una funzionalità di estendibilità per i produttori di fotocamere per creare applicazioni personalizzate in grado di configurare la fotocamera e regolare le impostazioni predefinite dell'immagine.

Introduzione

Windows 11 offre un framework di app complementare alla fotocamera che consente ai produttori di sviluppare applicazioni con le funzionalità seguenti:

Possibilità di visualizzare e/o modificare le stesse impostazioni predefinite supportate dalla pagina delle impostazioni della fotocamera (ad esempio Luminosità, Contrasto, Effetti di sfondo e così via).
Possibilità di registrare, aggiornare o eliminare le impostazioni predefinite per altri controlli fotocamera noti a Windows, ma che non vengono esposti tramite la pagina delle impostazioni della fotocamera (ad esempio, il controllo Hue).
Possibilità di registrare, aggiornare o eliminare le impostazioni predefinite dei valori per i controlli fotocamera proprietari del produttore (ad esempio, il controllo on/off per l'effetto di regolazione dell'illuminazione personalizzata di un produttore della fotocamera).

Quando una fotocamera registra un'app complementare associata, viene aggiunta una voce alla pagina delle impostazioni della fotocamera. Se l'app è installata, può essere avviata dalla pagina delle impostazioni della fotocamera, altrimenti viene visualizzato un collegamento a Microsoft Store per scaricarlo.

Le app complementari hanno accesso speciale a un'API che consente di registrare, aggiornare o eliminare valori predefiniti come la pagina delle impostazioni della fotocamera.

Terminologia e prerequisiti

Termine	Definizione
App complementare	Applicazione personalizzata sviluppata dal produttore della fotocamera che consente la configurazione e la gestione di una fotocamera oltre alla pagina delle impostazioni della fotocamera.
Valore corrente	Valore di un controllo fotocamera attualmente attivo nell'ISP della fotocamera e mantenuto nella memoria temporanea della fotocamera.
Valore predefinito	Valore iniziale di un controllo fotocamera archiviato su disco e salvato per una fotocamera specifica, per un account utente specifico, in un PC specifico.
HSA	App di supporto hardware, un framework supportato da Microsoft per scaricare e installare automaticamente le app associate all'hardware da Microsoft Store quando il dispositivo è connesso.
NPU	Unità di elaborazione neurale, hardware dedicato progettato per elaborare carichi di lavoro di intelligenza artificiale con velocità effettiva elevata ed efficienza.
Effetti di Windows Studio	Raccolta di effetti video disponibili su PC Windows con NPU.
UVC	Usb Video Class, l'interfaccia standardizzata per il controllo e lo streaming da fotocamere connesse USB.

Requisiti dell'app complementare

Le app complementari devono essere incluse in un pacchetto con un'identità del pacchetto. L'app complementare deve essere rilasciata anche in Microsoft Store, che consente alla pagina delle impostazioni della fotocamera di guidare i clienti nello Store per installare l'app se non è già installata.

Le applicazioni desktop tradizionali senza un'identità del pacchetto non possono essere usate come app complementare.

App complementari come HSA

Le app complementari non devono essere configurate anche come app di supporto hardware, ma è altamente consigliata. Gli HSA sono app speciali in Microsoft Store associate a un dispositivo hardware specifico. Quando il dispositivo è connesso a un PC, il modulo di protezione hardware viene scaricato e installato automaticamente da Microsoft Store quando disponibile.

Associare un'app complementare a una fotocamera

Il produttore di una fotocamera può associare un'app complementare popolando una chiave di proprietà del dispositivo specifica al nome della famiglia di pacchetti (PFN) dell'app complementare:

Nome	Type	Dati
SCSVCamPfn	REG_SZ	<PFN>

Per identificare il pfn dell'app complementare, eseguire Get-AppxPackage da PowerShell, ad esempio:

Get-AppxPackage -Name CompanionAppName

Per associare l'app complementare a una fotocamera, usare un descrittore MSOS in una fotocamera UVC o la direttiva AddReg nell'INF del driver della fotocamera. Ad esempio, usando il file INF:

[SocCaptureSim.RearCamera.AddReg]

HKR,,SCSVCamPfn,,%AppPFN%

...

[Strings]

AppPFN="Contoso.CameraCompanion_xxxxxxxx00000"

Quando un'app complementare è associata a una fotocamera, la pagina delle impostazioni della fotocamera include un collegamento all'app complementare sotto l'intestazione "Impostazioni correlate" della pagina delle impostazioni specifiche della fotocamera.

Se l'app complementare è già installata, viene visualizzato un collegamento a "Apri {nome app complementare}". Quando si fa clic, l'app viene avviata.

Se l'app complementare non è già installata, viene visualizzato un collegamento per avviare Microsoft Store per scaricare e installare l'app.

Una fotocamera può avere una sola app complementare associata.

Avviare un'app complementare dalla pagina delle impostazioni della fotocamera

Quando la pagina delle impostazioni della fotocamera avvia l'app complementare, il collegamento simbolico della fotocamera viene passato come contesto tramite gli argomenti Application.OnLaunched .

Argomento	Type	Dati
cameraId	String	Collegamento simbolico

Questa funzionalità consente all'app complementare di visualizzare le impostazioni corrette della fotocamera negli scenari seguenti:

Una singola app complementare supporta più fotocamere su un singolo sistema (ad esempio, un'applicazione fornita dall'OEM supporta le fotocamere anteriore e posteriore su un tablet).
Un cliente ha due delle stesse fotocamere (o della stessa marca) connesse al sistema gestito dalla stessa app complementare.

Avviare la pagina delle impostazioni della fotocamera da un'app complementare

Un'app complementare può avviare la pagina delle impostazioni della fotocamera di Windows usando un URI di deeplink. Per altre informazioni, vedi Avviare la pagina delle impostazioni della fotocamera.

Configurare i valori predefiniti dalle app complementari

Un'app complementare può usare l'API IMF Fotocamera ConfigurationManager per configurare la configurazione del valore predefinito dell'utente corrente. Questa API consente all'app complementare di leggere i valori predefiniti configurati (ad esempio, i valori predefiniti impostati dall'utente usando la pagina delle impostazioni della fotocamera), modificare i valori predefiniti, registrare i nuovi valori predefiniti o rimuovere i valori predefiniti salvati.

I valori predefiniti vengono registrati nel database del sistema come coppia di GUID della proprietà KS e valore corrispondente. In questo modo l'architettura può essere indipendente dalla definizione della proprietà KS. Questa flessibilità consente a un'app complementare di impostare, modificare o eliminare i valori predefiniti per una delle impostazioni seguenti:

Impostazioni configurabili anche tramite la pagina delle impostazioni della fotocamera (ad esempio Luminosità, Contrasto, Effetti di sfondo e così via)
Impostazioni per altri controlli fotocamera noti a Windows, ma non vengono esposti tramite la pagina delle impostazioni della fotocamera (ad esempio, il controllo Hue)
Impostazioni per i controlli fotocamera proprietari del produttore (ad esempio, il controllo on/off per l'effetto di regolazione personalizzata dell'illuminazione di un produttore della fotocamera)

Configurare la luminosità da un'app complementare

Ci sono alcuni modi per una fotocamera per controllare la luminosità effettiva dell'immagine acquisita. Ad esempio, la luminosità può essere aumentata applicando un semplice guadagno all'immagine o può essere aumentata aumentando il tempo di esposizione della fotocamera.

Windows supporta un controllo luminosità legacy (KSPROPERTY_VIDEOPROCAMP_BRIGHTNESS) progettato con semplici controlli di guadagno. Windows supporta anche un controllo di compensazione dell'esposizione (KSPROPERTY_CAMERACONTROL_EXTENDED_EVCOMPENSATION) progettato per gestire una distorsione positiva o negativa del valore di esposizione all'algoritmo auto exposure di una fotocamera.

Indipendentemente dal controllo Luminosità utilizzato da una fotocamera, deve essere implementato nella fotocamera in modo che quando "centrato", la luminosità sia neutra e che il cliente possa applicare un offset aumentando o abbassando il valore. Per una migliore qualità dell'immagine, è consigliabile che le fotocamere supportino il controllo di compensazione dell'esposizione in modo che se un cliente regola il controllo Luminosità nella pagina delle impostazioni della fotocamera o in un'app complementare, la fotocamera viene regolata per applicare una distorsione positiva o negativa fissa all'esposizione indipendentemente dalle condizioni di illuminazione in qualsiasi momento.

Per altre informazioni, vedi la pagina delle impostazioni della fotocamera per il comportamento del controllo Luminosità nella pagina delle impostazioni della fotocamera in base al controllo implementato dalla fotocamera. Se un'app complementare offre anche un dispositivo di scorrimento Luminosità, è fondamentale replicare la logica per garantire la sincronizzazione tra il dispositivo di scorrimento Luminosità nella pagina delle impostazioni della fotocamera e l'app complementare.

L'esempio di app complementare collegato di seguito include un'implementazione di riferimento di questa logica.

Monitoraggio delle modifiche al valore corrente in tempo reale

Se un'app complementare è in esecuzione contemporaneamente alla pagina delle impostazioni della fotocamera, è possibile che il cliente modifichi un valore predefinito usando la pagina delle impostazioni della fotocamera mentre l'app complementare è in esecuzione simultanea in modalità condivisa per visualizzare un'anteprima. In questo caso, è consigliabile che l'app complementare monitori le modifiche apportate al valore predefinito dei controlli in modo che possa rimanere sincronizzato.

A tale scopo, l'app complementare può usare il FMI Fotocamera ControlMonitor per monitorare le modifiche apportate al valore corrente dei controlli (proprietà KS) di interesse. Queste modifiche possono verificarsi a causa di:

Un'applicazione fotocamera (ad esempio, Microsoft Teams) usa la fotocamera e apporta una modifica al valore corrente di un controllo.
La pagina delle impostazioni della fotocamera usa la fotocamera e apporta una modifica al valore predefinito di un controllo (che aggiorna anche il valore corrente).

Questa API può essere usata come trigger per rileggere il valore predefinito per un controllo di interesse usando l'API IMF Fotocamera ConfigurationManager e aggiornare l'interfaccia utente se sono stati modificati valori predefiniti.

Esempi di app complementari

Un'app complementare di esempio è disponibile in GitHub: esempio di Fotocamera Impostazioni External Impostazioni App. Questo esempio illustra come usare l'API IMF Fotocamera ConfigurationManager per modificare il valore predefinito per contrasto, luminosità e segmentazione dello sfondo.

Un'altra applicazione di esempio che illustra come usare l'API IMF Fotocamera ControlMonitor per monitorare le modifiche ai controlli di interesse è disponibile nell'esempio GitHub: ControlMonitorApp.