Guia do Usuário do Imervue

Uma estação de trabalho de imagens acelerada por GPU que oferece quatro abas principais. A maior parte deste guia está organizada em torno dessas quatro seções.

Aba

O que faz

Imervue

Navega, visualiza, organiza, pesquisa e processa em lote sua biblioteca de imagens. Consulte Aba Imervue — Visualizador de Imagens e Biblioteca.

Modify

Pipeline de revelação não destrutiva — sliders, curvas, LUTs, máscaras, retoque, multi-imagem. Consulte Aba Modify — Revelação Não Destrutiva.

Paint

Estúdio raster de pintura completo com pincéis, camadas, animação, ferramentas para mangá e I/O de PSD. Consulte Aba Paint — Editor Raster Completo.

Puppet

Animador de fantoches 2D com rig construído do zero — meshes, deformadores, parâmetros, movimentos, física. Consulte Aba Puppet — Animação 2D com Rig.

As seções Primeiros Passos, Referência, Sistema de Plugins e Servidor MCP que vêm a seguir são transversais — aplicam-se a todas as quatro abas.

Primeiros Passos

Ao abrir o Imervue, você verá três áreas:

+------------+----------------------+----------+
|  Árvore    |                      |   EXIF   |
|  de        |   Visualizador       |  Barra   |
|  Pastas    |   de Imagens         | lateral  |
+------------+----------------------+----------+

  • Esquerda: Árvore de pastas. Clique em uma pasta para navegar pelas imagens internas.

  • Centro: Área de exibição de imagens. Mostra todas as imagens em uma grade de miniaturas.

  • Direita: Barra lateral EXIF. Exibe as informações de captura da imagem selecionada.

Abrindo Imagens

Método

Como

Abrir Pasta

Arquivo > Abrir Pasta, depois escolha um diretório

Abrir Imagem Individual

Arquivo > Abrir Imagem, depois escolha um arquivo

Arrastar e Soltar

Arraste uma imagem ou pasta diretamente para a janela

Abrir pelo Explorador

Clique com o botão direito em uma imagem > Open with Imervue (requer associação de arquivos)

Arquivos Recentes

Arquivo > Recentes, reabra rapidamente uma pasta visitada anteriormente

Formatos Suportados

  • Padrão: PNG, JPEG, BMP, TIFF, WebP, GIF, APNG, SVG

  • RAW: CR2 (Canon), NEF (Nikon), ARW (Sony), DNG (Adobe), RAF (Fujifilm), ORF (Olympus)

Organizando Imagens

Avaliação e Favoritos

No modo Deep Zoom você pode avaliar imagens rapidamente:

Ação

Tecla

Alternar favorito

0

Avaliar 1 – 5 estrelas

1 2 3 4 5 (pressione novamente para limpar)

Rótulos de Cor (F1 – F5)

Marcadores de cor independentes baseados em flags, armazenados separadamente da avaliação por estrelas de 1 a 5. Úteis para categorização rápida (ex.: vermelho = candidatos a rejeição, verde = selecionadas, azul = a retocar).

Ação

Tecla

Vermelho / Amarelo / Verde / Azul / Roxo

F1 / F2 / F3 / F4 / F5 (pressione a mesma tecla novamente para limpar)

Aplicação em lote à seleção

Selecione várias miniaturas, depois pressione a tecla F correspondente

Filtrar por cor

Filtrar > Por Rótulo de Cor > escolha uma cor / Qualquer rótulo / Sem rótulo

A barra de status mostra um chip colorido para a imagem atual. As miniaturas exibem uma faixa colorida na borda esquerda. A Visualização em Lista tem colunas dedicadas de Rótulo e Avaliação por Estrelas pelas quais você pode ordenar — clique em qualquer célula na coluna de estrelas para definir a avaliação sem sair da lista.

Marcadores (Bookmarks)

Salve imagens usadas com frequência como marcadores para acesso rápido posteriormente.

Ação

Método

Adicionar / remover marcador

Pressione B no modo Deep Zoom

Gerenciar marcadores

Arquivo > Marcadores

Tags e Álbuns

Categorize suas imagens com tags e álbuns.

Ação

Método

Abrir gerenciador

Pressione T ou Arquivo > Tags e Álbuns

Marcar uma imagem com tag

Clique com o botão direito na imagem > Adicionar à Tag

Adicionar ao álbum

Clique com o botão direito na imagem > Adicionar ao Álbum

Filtrar por tag/álbum único

Filtrar > Por Tag / Por Álbum

Filtro multi-tag (E / OU)

Filtrar > Filtro Multi-Tag… — marque várias tags ou álbuns, escolha Qualquer (OU) ou Todos (E)

Classificação e Filtragem

Recurso

Localização no Menu

Ordenar por nome

Ordenar > Por Nome

Ordenar por data de modificação

Ordenar > Por Data de Modificação

Ordenar por tamanho do arquivo

Ordenar > Por Tamanho do Arquivo

Ordenar por resolução

Ordenar > Por Resolução

Crescente / Decrescente

Ordenar > Crescente / Decrescente

Filtrar por extensão

Filtrar > JPEG / PNG / RAW etc.

Filtrar por avaliação

Filtrar > Por Avaliação

Filtrar por rótulo de cor

Filtrar > Por Rótulo de Cor (Todos / Qualquer rótulo / Sem rótulo / Vermelho / Amarelo / Verde / Azul / Roxo)

Filtro avançado

Filtrar > Filtro Avançado… — faixa de resolução, faixa de tamanho de arquivo, orientação (paisagem / retrato / quadrada), faixa de data de modificação

Limpar filtros

Filtrar > Limpar Filtro

Modo de Navegação (Grade / Lista)

Alterne o navegador de imagens entre a grade de blocos e uma lista detalhada ordenável:

  • Ctrl + L — alternar Grade ↔ Lista

  • Menu: Tamanho da Miniatura > Modo de Navegação > Grade / Lista

  • No modo Lista, qualquer coluna (incluindo Rótulo) é ordenável; clique duas vezes em uma linha ou pressione Enter para abrir o Deep Zoom.

Editando Imagens (Aba Modify)

Mude para a aba Modify na parte superior da janela para entrar no modo de edição. Você também pode pressionar E ou clicar com o botão direito > Modify no modo Deep Zoom.

+--------+----------------------+------------+
| Tira   |                      | Propriedades|
| de     |   Tela (desenhe aqui)| Pincéis    |
| Ferr.  |                      | Revelar    |
+--------+----------------------+------------+

Ferramentas de Anotação (Painel Esquerdo)

Ferramenta

Ícone

Descrição

Selecionar

⬚

Selecionar anotações existentes; arraste para mover

Retângulo

▢

Desenhar retângulos

Elipse

◯

Desenhar elipses ou círculos

Linha

╱

Desenhar linhas retas

Seta

→

Desenhar setas

Mão livre

✎

Desenho de forma livre

Texto

T

Adicionar texto à imagem

Mosaico

▦

Pixelar uma região selecionada

Desfoque

◌

Aplicar desfoque gaussiano em uma região selecionada

Tip

Pressione Seta Esquerda / Seta Direita enquanto estiver na aba Modify para alternar entre imagens sem sair do editor.

Tipos de Pincel (Painel Direito)

Pincel

Efeito

Caneta

Linha fina padrão, o pincel mais comum

Marcador

Traços mais grossos e semitransparentes

Lápis

Linha fina ligeiramente esmaecida

Marca-texto

Largo e altamente transparente, como um marca-texto real

Spray

Efeito de pontos dispersos

Caligrafia

A largura do traço varia com a direção

Aquarela

Efeito suave de bordas úmidas com mistura

Carvão

Traço áspero e texturizado

Giz de cera

Textura cerosa, como giz de cera

Propriedades de Desenho (Painel Direito)

Propriedade

Descrição

Cor

Clique na amostra de cor para escolher uma cor de desenho

Largura do Traço

Arraste o slider para ajustar a espessura da linha (1 – 40)

Opacidade

Ajuste a transparência (0 % – 100 %)

Fonte

Escolha a fonte para a ferramenta Texto

Tamanho da Fonte

Ajuste o tamanho do texto (6 – 200 px)

Ajustes de Imagem (Painel Direito, Inferior)

Slider

Função

Exposição

Ajustar o brilho geral

Brilho

Ajuste fino das áreas claras e escuras

Contraste

Ajustar a diferença entre claros e escuros

Saturação

Ajustar a vivacidade da cor

Balanço de Branco — Temperatura

Deslocamento quente / frio (azul → amarelo); útil para luz mista ou fotos em ambientes fechados

Balanço de Branco — Matiz

Deslocamento magenta / verde; corrige dominância fluorescente

Sombras

Levantar ou esmagar detalhes em regiões de tons escuros

Meios-Tons

Ajustar a faixa tonal intermediária sem afetar pretos e brancos

Realces

Recuperar realces estourados ou empurrar áreas claras ainda mais

Vibração

Reforço de saturação consciente — protege tons de pele e cores já saturadas

Esses ajustes são não destrutivos. Cada slider grava em uma receita de edição armazenada por imagem; pressione Reset a qualquer momento para restaurar o original, ou Ctrl + Z para voltar passo a passo nas alterações individuais. As receitas sobrevivem a reinicializações e podem ser exportadas / sincronizadas via o fluxo de sidecar XMP descrito na seção Metadados.

Salvar e Desfazer

Botão

Descrição

Salvar

Gravar anotações e ajustes no arquivo original

Desfazer

Desfazer a última operação

Refazer

Refazer uma operação desfeita

Resetar

Limpar todos os ajustes de imagem

Espaço de Trabalho Paint (Aba Paint)

A terceira aba principal — Paint — é um espaço de trabalho completo para pintura com documentos em múltiplas abas, camadas vetoriais e raster, ferramentas para mangá, quadros de animação e importação/exportação PSD. Mude para ela pela barra de abas ou pressione E no modo Deep Zoom para enviar a imagem atual diretamente para uma nova aba Paint.

Destaques de usabilidade — o espaço de trabalho Paint vem com um cursor completo de tamanho de pincel que escala com o zoom, ícones de cursor distintos por ferramenta, um padrão de checker de transparência sob a tela, sobreposição de destaque para arrastar-e-soltar, asterisco de modificado por aba, confirmações via toast para desfazer / refazer, um segmento de status de autosalvamento na barra de status, e um prompt de recuperação de autosalvamento na inicialização que apresenta snapshots de uma sessão anterior que travou.

Atalhos para usuários avançados: Tab alterna todos os docks para pintura sem distrações, Ctrl+Tab alterna entre abas, , / . alternam os tipos de pincel, 0–9 definem a opacidade do pincel em passos de 10 %, Alt+[ / Alt+] percorrem a camada ativa, e o clique com o botão direito na tela abre um menu rápido com Desfazer / Refazer / Selecionar Tudo / Desselecionar / Ajustar / 100 %.

O dock de cores agora expõe um slot “transparente / sem cor” (BG padrão = transparente), e tanto preenchimento quanto varinha mágica respeitam limites de alfa, de forma que pixels apagados não vazam para uma nova pintura.

+------+----------------------+----------------+
| Barra|                      | Cor · Pincel   |
| de   |   Tela (pintar)      | Camada · Nav.  |
| Ferr.|                      | Material · …   |
+------+----------------------+----------------+

Os docks do lado direito (Cor, Pincel, Camada, Navegador, biblioteca de Materiais, Histórico, Paleta, Referência, Histograma, Animação) são organizados em abas em uma única coluna para que a tela mantenha toda a altura visível. Arraste o título de qualquer dock para reorganizar ou flutuar um painel, depois salve o resultado via Configurações > Layouts de Espaço de Trabalho….

Paleta de Ferramentas (Tira Esquerda)

Ferramenta

Atalho

Finalidade

Pincel

B

Pintar com o tipo de pincel ativo

Borracha

E

Apagar alfa na camada ativa

Preenchimento (balde)

G

Preenchimento por inundação com tolerância / contíguo / amostrar todas as camadas

Conta-gotas

I

Selecionar cor de primeiro plano a partir da tela

Mover

V

Transladar a camada ativa ou seleção

Retângulo / Laço / Varinha / Seleção Rápida

M / L / W

Ferramentas de seleção com modos Substituir / Adicionar / Subtrair / Interseccionar

Texto

T

Editor de texto inline com fonte / tamanho / negrito / itálico

Gradiente

U

Preenchimento por gradiente Linear / Radial / Angular / Diamante

Desfoque / Esfumar

R

Manipulação local de pixels

Caneta (Bezier)

P

Caminho vetorial com edição de âncoras / alças

Carimbo de Clonar

S

Shift+clique define a origem, clique carimba com pluma

Balão de Fala

Ctrl + B

Balão estilo quadrinho / mangá com cauda automática

Retângulo / Elipse / Linha / Polígono

Shift + R/E/I/P

Primitivas vetoriais de forma com traço + preenchimento

Recortar

C

Recorte interativo com presets de proporção

Transformar

Ctrl + T

Alças de transformação livre / escala / rotação / inclinação

Mão

H

Deslocar a tela arrastando com o cursor

Zoom

Z

Clique para aproximar, Alt-clique para afastar

Pincéis

Pincel

Efeito

Caneta

Linha nítida e antialiased, o pincel do dia a dia

Marcador / Marca-texto

Traços largos e semitransparentes que se sobrepõem

Lápis

Linha fina de grafite levemente texturizada

Spray

Pontos dispersos controlados por densidade e fluxo

Caligrafia

Largura varia com a direção do traço

Aquarela

Vazamento de borda úmida e mistura suave

Carvão / Giz de cera

Traços ásperos e texturizados com inclinação por pressão

Cada pincel expõe Tamanho / Opacidade / Dureza / Densidade / Modo de Mistura no dock Pincel e na barra de Opções superior. Use Configurações > Curva de Pressão… para remapear a pressão da tablet para largura ou opacidade, e Editar > Capturar Ponta de Pincel… para transformar uma seleção em uma ponta de pincel personalizada.

Camadas

O dock Camada oferece miniaturas, alternâncias de visibilidade, renomeação inline, arrastar para reordenar, e o modo de mistura + opacidade da camada ativa. O menu Camada adiciona:

  • Nova / Vetorial / Duplicar / Mesclar Abaixo (Ctrl + Shift + N / Ctrl + Shift + V / Ctrl + J / Ctrl + E)

  • Máscaras — Adicionar Máscara / A partir da Seleção / Inverter / Aplicar / Excluir (Ctrl + Shift + M adiciona; Ctrl + Alt + Shift + M adiciona a partir da seleção)

  • Máscara de Recorte — recortar a camada acima ao alfa atual (Ctrl + Alt + G)

  • Efeitos de Camada — Sombra Projetada · Brilho Externo · Traço; limpar efeitos

  • Camada de Referência — fixar uma camada como fonte do conta-gotas

  • Camada 1-bit — alternar a camada ativa para uma camada binária de line-art

  • Dividir Camada por Cor — dividir uma camada de cor plana em uma camada por cor para facilitar repinturas com balde

  • Mapa de Gradiente — submenu de presets (sépia / pôr-do-sol / cianotipo …)

Seleções

Use as ferramentas retângulo / laço / varinha / seleção rápida, depois o Traçar Seleção… no menu Editar para contornar a marquise com o pincel atual. Q alterna o Modo Máscara Rápida — pinte com qualquer pincel para refinar a borda da seleção em vermelho, depois pressione Q novamente para convertê-la de volta em uma marquise.

Animação

O dock Animação transforma o documento em uma tira de quadros:

  • Adicionar Quadro captura o estado atual da camada em um novo keyframe.

  • Clique na miniatura de um quadro para saltar até ele.

  • Onion Skin (menu Visualizar) sobrepõe quadros vizinhos com baixa transparência.

  • Exporte a tira via Arquivo > Exportar páginas (CBZ para leitores de quadrinhos, PDF para impressão) ou Exportação de Animação para MP4 / GIF.

Filtros

Filtro abre uma caixa de diálogo com pré-visualização ao vivo para cada efeito:

  • Níveis — sliders preto / gama / branco, por canal

  • Curvas — pontos arrastáveis (RGB / R / G / B) com interpolação cúbica monotônica

  • Posterizar — quantizar cor em N passos

  • Limiar — converter para preto / branco puro em um corte

  • Balanço Automático de Cor — neutralizar dominâncias via grey-world / white-patch

  • Granulação de Filme — ruído de luminância com tamanho e quantidade ajustáveis

  • Converter para Meio-Tom — tela de pontos estilo jornal

Auxílios de Visualização

  • Grade de Pixels (Ctrl + Shift + ') — sobrepor grade de um pixel em zoom alto

  • Encaixar em Pixel / Bordas — colocação sub-pixel travada em coordenadas inteiras

  • Onion Skin — sobreposição de vizinhos para animação

  • Guias de Sangria — guias de sangria de impressão / zona segura

  • Rotacionar Tela (Ctrl + Shift + H) — rotação da visualização sem rasterizar

I/O de Arquivos

  • Abrir PSD… (Ctrl + O) e Salvar como PSD… (Ctrl + S) — round-trip de PSD em camadas com máscaras, modos de mistura e efeitos de camada

  • Exportar imagem… — achatar e salvar como PNG / JPEG / WebP / BMP / TIFF

  • Exportar páginas → CBZ / → PDF — exportação de documento multi-quadro para quadrinhos

  • Importar / Exportar presets de pincel, Importar paleta — compartilhar recursos entre instalações

  • Snapshots de autosalvamento — snapshots periódicos em segundo plano com restauração do último a partir do menu Arquivo

Layouts de Espaço de Trabalho

Configurações > Layouts de Espaço de Trabalho… salva o arranjo dos docks, o estado das opções de ferramenta e os painéis ativos com um nome, depois alterna entre eles com um clique — por exemplo, um layout “Desenho” com os docks Pincel + Cor em destaque e um layout “Composição” com os docks Camada + Histórico expandidos.

Espaço de Trabalho Puppet (Aba Puppet)

A quarta aba principal — Puppet — é um sistema de animação de fantoches 2D com rig construído do zero. Faz o que o Live2D faz (rigs de deformação de mesh, parâmetros, motions, física, expressões, grupos de pose, sincronização labial, rastreamento por webcam) mas sem SDK proprietário, sem `live2d-py`, e com um formato de arquivo .puppet totalmente aberto.

Note

O tutorial completo de ponta a ponta — partindo de uma instalação nova até uma transmissão ao vivo no OBS ou um MP4 renderizado — está em puppet_guide.md na raiz do repositório (com espelhos em puppet_guide.zh-TW.md e puppet_guide.zh-CN.md). Esta seção é a referência; o guia é o passo a passo.

+-----------+----------------------+----------------+
|  Barra de |                      |   Dock         |
|  Ferr.    |   Canvas GL          |   Parâmetros   |
|           |                      |                |
+-----------+----------------------+                |
|               Dock Motions                        |
+---------------------------------------------------+

Fluxo de Trabalho de Ponta a Ponta

  1. Importar um PNG — a barra de ferramentas Import PNG… executa puppet.auto_mesh.puppet_from_png: grade triangulada limitada por alfa, um drawable, pronto para renderizar.

  2. Adicionar um deformador — Add Rotation Deformer (âncora + ângulo) ou Add Warp Deformer (lattice Bezier de linhas × colunas; os vértices fora dos limites passam sem alteração).

  3. Adicionar um parâmetro — Add Parameter adiciona um slider ao dock Parâmetros à direita com id auto-nomeado (Param1, Param2, …).

  4. Definir keys — arraste o slider para um extremo, edite a forma do deformador em código ou via edição de mesh, pressione Set key. Repita no neutro e no extremo oposto. O runtime então faz lerp dos campos do deformador entre keys adjacentes sempre que o slider se move.

  5. Salvar — Save As… grava o rig + texturas + motions + expressões + física em um único zip .puppet que você pode compartilhar ou abrir depois via Open Puppet….

Experimente um Exemplo Pronto

O repositório inclui uma demo totalmente riggada em examples/puppet/march_7th.puppet — um rig Cubism Live2D de 307 drawables convertido in-tree. Texturas e morphs de vértice por parâmetro são embutidos no zip .puppet, então a demo abre com o requirements.txt padrão sem redistribuir o Cubism SDK.

O rig carrega 203 parâmetros padrão Cubism (ParamAngleX/Y/Z, ParamEyeLOpen/ROpen, ParamBreath, ParamMouthOpenY, …), então todo driver de entrada padrão (webcam, piscar, sincronização labial, olhar do cursor) o aciona sem configuração por rig. Nove motions em loop estão incluídos no pacote — loops de idle do Cubism convertidos pelo autor mais loops de gestos de referência nos grupos Idle e TapHead.

Abra a aba Puppet, clique em Open Puppet…, aponte para march_7th.puppet — a figura aparece centralizada. Arraste qualquer slider de parâmetro para acionar uma articulação, ou clique em um dos motions no dock Motions — clique único vincula o motion e inicia a reprodução imediatamente.

Executando o exemplo incluído, passo a passo:

  1. Inicie o Imervue. A partir do código-fonte: python -m Imervue. A partir do build empacotado: execute o executável / bundle de aplicativo Imervue. O diretório examples/ é empacotado tanto na wheel quanto no EXE Nuitka, então o rig está no disco onde quer que você tenha instalado.

  2. Clique na aba Puppet no topo da janela.

  3. Barra de ferramentas → File > Examples > March 7Th (ou o dropdown Examples ▾ da barra de ferramentas). O rig de 307 drawables carrega centralizado e o dock de parâmetros é preenchido com os 203 sliders padrão Cubism.

  4. No dock Motions inferior, clique uma vez em qualquer entrada de motion (zhaiyan, zhaoxiang, idle_breath, tap_head …). A reprodução inicia imediatamente; clique novamente para parar, ou escolha um motion diferente para fazer cross-fade nele.

  5. Alterne os interruptores de entrada ao vivo na barra de ferramentas para acionar o rig com suas próprias entradas — Drag-track head para olhar do cursor, Auto-blink para fechamento cíclico dos olhos, Auto idle + Idle motions para respiração + clipes Idle aleatórios, Mic lip-sync para abertura da boca a partir do RMS do microfone, Webcam tracking para cabeça + olhos + boca completos do FaceLandmarker do MediaPipe.

  6. Reset to rest na barra de ferramentas para todo motion, desativa todo driver ao vivo, limpa expressões / overrides de pose, e retorna todo parâmetro ao seu padrão — a ação canônica de “começar de novo”.

  7. Para abrir um rig diferente depois: File > Open Puppet… escolhe qualquer zip .puppet do disco; File > Examples ▾ permanece vinculado à lista incluída.

Formato de arquivo .puppet (v1)

Um arquivo .puppet é um arquivo zip:

my_character.puppet
├── puppet.json              # obrigatório — manifesto, drawables, deformadores, parâmetros
├── textures/
│   ├── face.png             # referenciado por drawables[].texture
│   └── body.png
├── motions/                 # opcional
│   ├── idle.json
│   └── wave.json
├── expressions/             # opcional
│   └── smile.json
└── physics.json             # opcional

Exemplo de puppet.json de nível superior:

{
  "version": 1,
  "size": [2048, 2048],
  "drawables": [ ... ],
  "deformers": [ ... ],
  "parameters": [ ... ],
  "motions": ["idle", "wave"],
  "expressions": ["smile"],
  "pose": {"groups": [ ... ]},
  "physics": "physics.json"
}

O schema completo (drawables, deformadores, parâmetros, motions, expressões, pose, física) está em Imervue/puppet/FORMAT.md no repositório. Somente JSON + PNG — sem binário proprietário, totalmente diff-vel via git.

Referência da Barra de Ferramentas

Ação

Finalidade

Open Puppet… / Examples ▾

Carrega um .puppet do disco, ou escolhe um dos rigs incluídos em examples/puppet/ diretamente da barra de ferramentas

Import PNG… / Import PSD… / Import Cubism…

Auto-mesh de um PNG, divisão por camadas de um PSD, ou sample-and-reconstruct de um rig Cubism. O seletor Cubism aceita tanto .moc3 quanto .model3.json; sem rig aberto, qualquer caminho executa a conversão completa .moc3 → .puppet (Cubism Native SDK fornecido pelo usuário). Escolher .model3.json com um rig carregado mescla seus metadados apenas-JSON (motions / expressões / física) no documento ativo.

Recent

Reabrir rapidamente um puppet aberto recentemente

Save As…

Gravar o rig atual como um zip .puppet

Add Rotation Deformer / Add Warp Deformer / Add Parameter

Criar o rig a partir da barra de ferramentas

Drag-track head

Offset do cursor → ParamAngleX / ParamAngleY + ParamEyeBallX / ParamEyeBallY

Auto-blink

Ciclo cosseno close→open em ParamEyeLOpen / ParamEyeROpen a cada ~4,5 s (caminho force-write ignora o no-change-skip do canvas para que drivers concorrentes não travem o piscar)

Mic lip-sync

RMS do microfone → ParamMouthOpenY (requer sounddevice)

Webcam tracking

FaceLandmarker da MediaPipe Tasks API → yaw / pitch / roll da cabeça + olhos + boca (requer opencv-python + mediapipe; abre uma caixa de diálogo de pré-visualização ao vivo com landmarks detectados)

Auto idle / Idle motions

Ciclo de respiração + drift em parâmetros padrão, mais ciclador aleatório opcional pelos motions do grupo Idle

Edit mesh

Clique e arraste vértices do canvas para refinar a mesh

Record motion

Captura mudanças de parâmetro em um novo Motion e o adiciona ao documento — bake-from-take, sem autoração manual de keys

Capture frame… / Record… / Export all motions…

Salvar um único PNG, alternar gravação de GIF / WebM / MP4, ou renderizar em lote cada motion do rig em seu próprio arquivo (tudo via o mesmo caminho de render off-screen apenas-personagem usado para streaming)

Output > Virtual camera / NDI output

Superfícies de streaming ao vivo — ver Streaming ao vivo para o OBS acima

Reset to rest

Snap-stop do player de motion, desativa todo driver ao vivo, limpa expressões / grupos de pose, restaura padrões de parâmetro

Fit to Window

Recentralizar + redimensionar o puppet no canvas

Gravando Seus Próprios Motions

Para capturar uma take customizada em vez de autorizar keyframes manualmente:

  1. Alterne Record motion na barra de ferramentas — uma caixa de diálogo de nome aparece.

  2. Enquanto grava, arraste sliders, habilite Webcam tracking, deixe a física rodar, qualquer coisa que escreva valores de parâmetro.

  3. Desative Record motion — o gravador bake do stream capturado a 30 Hz em um Motion com uma trilha de segmento linear por parâmetro que efetivamente se moveu (parâmetros que ficaram parados são descartados). O novo motion aparece no dock Motions inferior imediatamente, pronto para reproduzir / repetir / salvar.

Motions customizados salvos dessa forma fazem round-trip pelo mesmo payload JSON motions/<name>.json que os autorizados manualmente.

Streaming ao Vivo para o OBS

Dois caminhos de saída, ambos renderizando o puppet sozinho (sem fundo de checker, sem cromo do editor) em um framebuffer off-screen antes de entregá-lo à superfície de streaming. O lado mais longo da saída é limitado a 1080 px para que canvases nativos Cubism (March 7th é 3503×7777) não sejam rejeitados por drivers de câmera virtual DirectShow.

A. Virtual Camera — aparece como uma webcam na lista de fontes Video Capture Device do OBS. pip install pyvirtualcam mais o driver de plataforma: o OBS Studio 26+ inclui o driver OBS Virtual Camera no Windows / macOS (clique em Start Virtual Camera no OBS uma vez para registrá-lo); o Linux usa v4l2loopback-dkms + modprobe v4l2loopback exclusive_caps=1 card_label="Imervue". A barra de ferramentas Output > Virtual camera abre o stream.

DirectShow / AVFoundation / v4l2loopback são apenas RGB — sem canal alfa — então o Imervue preenche a área fora do personagem com magenta `#FF00FF` como uma chave de croma. Remova-o no OBS via o filtro Color Key:

  1. Clique com o botão direito na fonte Video Capture Device > Filters

  2. Effect Filters > + > Color Key

  3. Defina Key Color Type = Custom Color, Custom Color = HEX FF00FF, Similarity = 80–300, Smoothness = 30–50

O filtro permanece na fonte de modo que a chave de croma é reaplicada automaticamente sempre que a câmera virtual é retomada.

B. Saída NDI — transmissão LAN sub-50 ms carregando RGBA, então OBS / vMix compõem diretamente sobre suas próprias cenas sem passe de chave de croma. pip install ndi-python + o runtime NDI Tools + o plugin obs-ndi. A barra de ferramentas Output > NDI output transmite a fonte (nome padrão Imervue Puppet).

O ndi-python traz apenas uma source distribution; o pip o constrói a partir de C++ no momento da instalação. Usuários do Windows precisam do Visual Studio Build Tools 2022 (com workload C++), CMake no PATH, e o NDI SDK de <https://ndi.video/for-developers/ndi-sdk/> instalado no local padrão com a variável de ambiente NDI_SDK_DIR apontando para ele.

Veja puppet_guide.md § 1.2 para o passo a passo completo mais a lista de solução de problemas (câmera mostra magenta, falha de cmake do ndi-python, estiramento da câmera virtual, etc.).

Dependências Opcionais

  • sounddevice — captura de microfone para sincronização labial

  • opencv-python + mediapipe — rastreamento facial por webcam

  • imageio-ffmpeg — gravação MP4 / WebM (já incluído para o Slideshow Video)

  • pyvirtualcam — saída de câmera virtual (ver Streaming ao vivo)

  • ndi-python — saída NDI (ver Streaming ao vivo)

  • DLL Cubism Native SDK fornecida pelo usuário — conversão .moc3 → .puppet (a Free Material License da Live2D proíbe redistribuição; os usuários colocam o SDK em <cwd>/sdk/ ou definem a variável de ambiente CUBISM_CORE_DLL)

O plugin degrada graciosamente quando qualquer um deles está ausente — a alternância correspondente da barra de ferramentas volta a desligado e mostra uma dica “install <package>”. File > Install dependencies… instala em lote cada pacote Python opcional de uma vez.

Espaço de Trabalho Desktop Pet (Aba Desktop Pet)

Aba 5 — o Desktop Pet coloca qualquer personagem .puppet na sua área de trabalho como uma sobreposição sem moldura e transparente. A aba em si é um painel de controle; o personagem propriamente dito é uma janela de nível superior separada que compartilha todo o runtime do Puppet (motions, expressões, física, drivers de idle, entrada de microfone / webcam). O pet pode reagir a cliques, executar animações controladas por temporizador, seguir seu cursor, se ocultar enquanto outro aplicativo estiver em tela cheia e falar linhas personalizadas que você cria em um arquivo JSON.

Este capítulo é uma referência completa para a aba. Está organizado como:

  1. Início rápido — caminho de cinco passos, de “acabei de abrir o Imervue” até “tem um puppet na minha área de trabalho”.

  2. Carregando um rig — seletor de arquivos, exemplo incluído, restauração entre inicializações.

  3. A janela de sobreposição — todo comportamento em nível de janela (arrastar para mover, encaixe em borda, click-through, trava de âncora, sempre no fundo, ocultar em tela cheia, pausar quando oculto, opacidade, tamanho, restauração multi-monitor).

  4. Modelo de interação — áreas de acerto no clique esquerdo, menu de contexto completo no clique direito, bandeja do sistema.

  5. Drivers ao vivo — seis drivers de entrada opcionais e suas dependências opcionais.

  6. Pet script — o arquivo JSON que permite substituir a voz do pet por suas próprias linhas, agendar lembretes e vincular respostas por-área-de-acerto / por-motion.

  7. Persistência — o que é lembrado entre inicializações e o esquema exato de configurações.

  8. Criando um novo pet — ponteiro para a aba Puppet + o formato de arquivo .puppet.

  9. Solução de problemas — surpresas comuns e o que fazer a respeito.

Início rápido

  1. Mude para a aba Desktop Pet.

  2. Clique em Load bundled March 7th para usar o personagem incluído, ou em Open Puppet… para escolher seu próprio arquivo .puppet.

  3. A sobreposição aparece na sua área de trabalho e o checkbox Show pet on desktop é marcado automaticamente. (Se você quiser ocultar o pet sem fechar o Imervue, desmarque o checkbox ou use o ícone da bandeja do sistema.)

  4. Arraste o personagem para onde você quiser. Solte perto de uma borda da tela para encaixar rente a ela.

  5. Escolha os Live drivers que deseja — respiração de idle, blink, seguir cursor, lip-sync de microfone, rastreamento de webcam — a partir da aba do espaço de trabalho ou do menu de clique direito do pet.

Tudo que você configurar sobrevive à próxima inicialização, então o passo 5 é uma decisão única por rig / persona.

Carregando um rig

A aba expõe três caminhos de carregamento:

  • Open Puppet… — escolha qualquer arquivo .puppet do disco.

  • Load bundled March 7th — abre o rig fornecido em examples/puppet/march_7th.puppet. O resolvedor procura em examples_dir() primeiro (seguro para builds congelados em Nuitka / instalados via pip) e cai para uma busca relativa à raiz do repositório, para que o botão funcione em ambos os modos de execução.

  • Last rig — o rig carregado anteriormente é restaurado automaticamente na inicialização do Imervue a partir do campo last_rig_path das configurações; a aba Desktop Pet re-instancia a sobreposição invisivelmente para que o pet esteja a um clique de distância do mesmo estado em que você o deixou.

Um carregamento bem-sucedido marca automaticamente Show pet on desktop para que o pet apareça imediatamente. O caminho de falha deixa o checkbox em paz e escreve o erro no rótulo de status da aba.

A janela de sobreposição

O personagem vive em uma janela de nível superior, separada da janela principal do Imervue. A janela é sem moldura, não tem entrada na barra de tarefas e (por padrão) fica acima de qualquer outra janela.

Comportamentos da janela

Comportamento

Detalhe

Sobreposição sem moldura

Sem cromo de janela, sem botões de minimizar / fechar, sem entrada na barra de tarefas. O personagem é toda a superfície visível.

Fundo transparente

Tudo que o personagem não cobrir é totalmente transparente. A área de trabalho / aplicativo atrás do pet aparece pixel a pixel.

Arrastar para mover

Pressione o botão esquerdo em qualquer lugar do corpo, arraste, solte. O arrasto é reconhecido como clique apenas se o cursor se moveu menos de seis pixels — mover mais longe transforma o gesto em movimento e o handler de clique não dispara.

Encaixe em borda

Solte perto de uma borda da tela (padrão: dentro de 24 px) e o pet “estala” rente a essa borda. O limiar é configurável de 0 (desligado) a 200 (muito grudento). O encaixe roda independentemente em cada eixo, então arrastar para um canto acopla nas duas bordas de uma vez.

Clamp de excesso

Um arrasto que termina além de uma borda da tela é trazido de volta para dentro. Você não pode deixar o pet fora da tela onde não conseguiria pegá-lo de novo.

Modo click-through

Quando habilitado, todo evento de mouse atravessa o pet até o que estiver atrás. O personagem ainda é visível, mas não pode ser arrastado, clicado com o botão direito ou usado para disparar motions. Ative quando o pet for puramente decorativo.

Travar posição

Desativa o arrastar-para-mover sem afetar o click-through. Útil quando você colocou o pet exatamente onde queria e não quer que arrastos acidentais o movam.

Sempre no fundo

Inverte o pet de sempre-no-topo para sempre-no-fundo. O pet fica atrás de todas as outras janelas como um widget de área de trabalho. Também desativa a flag de aceitação de foco, então clicar no pet não o eleva.

Ocultar em tela cheia

Um polling em segundo plano a 1 Hz observa a janela em primeiro plano no monitor do pet. Quando essa janela cobre ≥ 99 % da tela com uma tolerância por-borda ≤ 4 px (capturando tanto tela cheia real quanto jogos em janela sem borda), o pet se oculta automaticamente. Quando a tela cheia termina, o pet reaparece na posição anterior. O detector usa a API Win32 GetWindowRect no Windows; no macOS / Linux ele faz no-op graciosamente (o pet permanece visível).

Pausa quando oculto

O tick de pintura de ~30 FPS e o tick de script de 1 Hz ambos param em hideEvent, então um pet oculto custa zero CPU. Eles retomam no próximo showEvent.

Tamanhos predefinidos

Pequeno (200 × 300), médio (320 × 480), grande (480 × 720). O pet redimensiona em torno do seu centro atual, então uma mudança de tamanho não o realoca. O encaixe roda novamente após o redimensionamento.

Slider de opacidade

10 – 100 %. Atua no nível da janela (via setWindowOpacity), então o pet inteiro desbota, não apenas a textura. O piso mínimo de 10 % existe para que você sempre possa ver e pegar o pet — totalmente invisível faria você o perder.

Memória de posição

O (x, y) pós-encaixe após cada soltura é persistido. Na próxima inicialização o pet retorna a essa coordenada de tela. Se a posição salva não cair mais dentro de nenhuma tela conectada (você desconectou um monitor desde a última inicialização), o pet cai de volta para o canto inferior direito da tela primária.

Modelo de interação

O pet responde à entrada do mouse via três canais independentes.

Clique esquerdo no corpo

A posição do clique é mapeada de volta para coordenadas do canvas do puppet (desfazendo o pan / zoom do canvas) e passa pelo pipeline existente de hit_test. O resultado dirige o comportamento da seguinte forma:

  1. Se um HitArea cobre o drawable clicado E essa área tem uma motion anexada, a motion é reproduzida.

  2. Independentemente de uma motion ter sido reproduzida, o pet pode abrir um balão de fala — veja a seção Pet script para a prioridade de escolha de linha.

  3. Se nenhuma área de acerto cobre o clique, o pet cai para uma saudação (da lista greetings do script ou da saudação embutida).

Um gesto de arrastar-para-mover suprime o handler de clique, então mover o pet não dispara motion / fala.

Clique direito em qualquer lugar do corpo

Abre um menu de contexto com a seguinte estrutura:

  • Hide pet — ação de nível superior que fecha a sobreposição.

  • Submenu Live drivers — seis toggles marcáveis (Auto idle, Idle motions, Auto-blink, Drag-track head, Mic lip-sync, Webcam tracking). O estado de marcação espelha o estado dos drivers ao vivo, então o menu mostra o que está rodando no momento.

  • Submenu Play motion — populado a partir da lista document.motions do rig ativo. Selecionar uma entrada reproduz essa motion (e pode disparar a voz do pet se o script associar uma linha a ela).

  • Submenu Apply expression — populado a partir de document.expressions do rig. Selecionar alterna a sobreposição de parâmetros da expressão.

  • Cinco toggles marcáveis de nível superior: Lock position, Click-through, Always on bottom, Hide on fullscreen, Speech bubble — acesso rápido aos mesmos toggles na aba do espaço de trabalho.

  • Submenu Size — Pequeno / Médio / Grande; o preset atual está marcado.

Os submenus de motion / expression ficam desabilitados quando nenhum rig está carregado.

Ícone da bandeja do sistema

Um ícone na bandeja (instanciado apenas em plataformas que reportam suporte a bandeja) fornece uma quarta superfície para as ações mais comuns:

  • Clique esquerdo alterna a visibilidade do pet.

  • Clique direito abre um menu com Show pet (marcável), Click-through, Open puppet…, Hide pet.

  • Os itens marcáveis Show / Click-through espelham o estado de marcação do espaço de trabalho via sync_visibility / sync_click_through, então eles permanecem sincronizados onde quer que o usuário alterne o switch correspondente.

Drivers ao vivo

Cada driver ao vivo é criado preguiçosamente na primeira ativação, então um pet dormente paga zero custo de timer / thread para drivers que você nunca liga. O estado de cada driver é persistido; ligar, fechar o Imervue e relançar reabre o pet com os mesmos drivers rodando.

Driver

O que faz

Dependência opcional

Auto idle

Respiração + deriva sutil em parâmetros padrão (ParamBreath etc.) para que o personagem pareça vivo quando nada mais estiver animando.

nenhuma

Idle motions

Escolhe aleatoriamente uma motion do grupo Idle do rig a cada poucos segundos e a reproduz. Para se nenhuma motion estiver em andamento no momento.

nenhuma

Auto-blink

Fecha e reabre os olhos em uma curva cosseno suave a cada ~4,5 s. O driver força a escrita do parâmetro para que outros drivers que mexem em valores de abertura de olhos não suprimam o blink.

nenhuma

Drag-track head

A cabeça + olhos viram em direção à posição global do cursor mesmo quando o cursor está fora do pet. Dirige ParamAngleX / ParamAngleY / ParamEyeBallX / ParamEyeBallY.

nenhuma

Mic lip-sync

A amplitude RMS do microfone dirige ParamMouthOpenY. O

sounddevice

Webcam tracking

O MediaPipe FaceLandmarker lê sua webcam a ~30 FPS e dirige a pose da cabeça + parâmetros de abertura de olhos + abertura de boca. Abre uma pequena janela de pré-visualização ao vivo para que você possa verificar se a câmera vê seu rosto.

opencv-python + mediapipe

Os dois drivers com dep opcional degradam graciosamente: se o pacote necessário não estiver instalado, alternar o checkbox volta para o desligado e o rótulo de status do espaço de trabalho mostra uma dica “install sounddevice” / “install opencv-python + mediapipe”.

Pet script — voz personalizada e eventos agendados

O balão de fala do pet recorre a um arquivo JSON que você pode criar e carregar pelo grupo Pet script na aba. O script governa quatro coisas:

  • Greetings — linhas padrão de clique quando nada mais específico combina.

  • Hit-area responses — buckets de linha por HitArea.id.

  • Motion lines — buckets de linha por nome-de-motion, disparados quando o pet inicia essa motion (seja de uma área de acerto ou do menu de contexto).

  • Scheduled chimes — linhas controladas por temporizador que disparam a cada every_seconds de tempo monotônico de relógio.

Esquema (versionado — campos futuros são compatíveis para frente):

{
  "version": 1,
  "name": "March 7th — playful voice",
  "greetings": [
    "Hi!", "Hello hello!", "Need a break?"
  ],
  "hit_responses": {
    "HitAreaHead": ["Hey, my head!", "Stop poking!"],
    "HitAreaBody": ["Hehe~", "Pat pat?"]
  },
  "motion_lines": {
    "wave": ["Hi!", "Hello!"],
    "curtsy": ["Cheers!"]
  },
  "scheduled": [
    {"every_seconds": 1800, "messages": ["Stretch break!"]}
  ]
}

Regras de carregamento:

  • Listas são amostradas em round-robin por bucket para que o usuário não veja a mesma linha duas vezes seguidas.

  • Chaves de nível superior desconhecidas são ignoradas (compatível para frente — um futuro arquivo v2 ainda carrega em um runtime v1).

  • Entradas de lista inválidas (tipo errado, entradas agendadas malformadas, every_seconds zero / negativo) são puladas — uma linha ruim não faz o carregamento inteiro falhar. Apenas JSON totalmente não parseável levanta um erro e expõe o caminho no rótulo de status.

  • A cascata de hit-area / motion / greeting é em camadas: um clique esquerdo consulta primeiro hit_responses[area.id], depois motion_lines[area.motion], depois greetings, depois o conjunto de saudações padrão embutido como piso.

  • O rastreamento de tempo usa time.monotonic para que suspender o notebook ou pular o relógio do sistema não possa disparar em excesso eventos enfileirados.

Reset to default descarta o script do usuário e reverte para o conjunto de saudações embutido; o caminho persistido do script é limpo para que a próxima inicialização não o recarregue.

Um exemplo funcional vive em examples/desktop_pet/march_7th.petscript.json — seis saudações, dois buckets de hit-area (cabeça / corpo), três linhas de motion (wave / curtsy / cheer) e um lembrete de alongamento a cada 30 minutos.

Persistência

Todo estado do Desktop Pet faz round-trip através de user_setting_dict["desktop_pet"] (um slot no arquivo padrão de configurações de usuário do Imervue). Cada campo tem um padrão + clamp de intervalo no carregamento, então um arquivo de configurações corrompido não pode travar o lançamento.

Campos persistidos

Campo

Padrão

Notas

last_rig_path

""

Restaurado automaticamente na inicialização se o arquivo ainda existir.

script_path

""

Restaurado automaticamente na inicialização se o script ainda fizer parse; um script ilegível reverte para os padrões silenciosamente.

position

[-1, -1]

Coordenada de tela (x, y) da última soltura de arrasto. -1, -1 significa “use o canto inferior direito da tela primária”. Desconectar monitores entre sessões cai de volta da mesma forma.

size_preset

"medium"

Um de small / medium / large.

opacity

1.0

Restringido a [0.1, 1.0]. Valores fora do intervalo resetam para o padrão.

click_through

false

anchor_locked

false

always_on_bottom

false

Mutuamente exclusivo com sempre-no-topo.

hide_on_fullscreen

true

Defina como false para manter o pet visível durante tela cheia.

snap_threshold

24

Restringido a [0, 200] px.

drivers

todos false

Sub-dict com chaves por id de driver (auto_idle, idle_motion, auto_blink, drag_track, mic_lipsync, webcam_tracking). Chaves desconhecidas fazem round-trip intactas para compatibilidade para frente.

show_on_launch

false

Mostra a sobreposição automaticamente quando o Imervue inicia.

speech_enabled

true

Quando false o balão de fala nunca aparece.

O comportamento de merge do dict de configurações é de um nível de profundidade: arquivos de configurações mais antigos sem chaves mais novas ainda produzem um dict de estado completo no carregamento (os padrões preenchem as lacunas); chaves mais novas que você salvou sobrevivem a um downgrade para um runtime mais antigo que não as conhece.

Criando um novo pet

Qualquer arquivo .puppet funciona como um personagem de Desktop Pet — a aba Desktop Pet é puramente uma camada de renderização + interação; a criação de rigs acontece na aba Puppet (veja Espaço de Trabalho Puppet (Aba Puppet)).

Para criar seu próprio rig de pet:

  1. Mude para a aba Puppet e importe uma arte via File > Import PNG… ou File > Import PSD…, ou puxe um modelo Cubism via File > Import Cubism….

  2. Crie deformadores de rotação / warp, parâmetros, motions, expressões e (opcionalmente) áreas de acerto vinculadas a partes do corpo para que o handler de clique esquerdo do Desktop Pet possa disparar motions.

  3. Salve o rig via File > Save As… em um zip .puppet.

  4. Volte para a aba Desktop Pet e carregue o novo arquivo via Open Puppet….

Se seu rig define entradas HitArea, você pode criar linhas de balão de fala por área de acerto em um .petscript.json cujas chaves hit_responses combinam com os ids das áreas.

Solução de problemas

O pet aparece dentro de um retângulo cinza em vez de ser totalmente transparente. O atributo de fundo translúcido em nível de SO requer uma superfície GL ciente de alfa mais atributos correspondentes no widget GL incorporado. Certifique-se de que nenhuma ferramenta de gerenciamento de janelas de terceiros esteja sobrepondo o atributo WA_TranslucentBackground na janela de sobreposição (alguns gerenciadores de janelas personalizados no Linux fazem isso). No Windows / macOS isso deve “simplesmente funcionar”.

“Load bundled March 7th” reporta que o arquivo não foi encontrado. O resolvedor consulta primeiro examples_dir() (a localização segura para congelamento usada por builds empacotados) e cai para um caminho relativo ao CWD. Se nenhum dos dois contiver o rig, o rótulo de status expõe o caminho esperado. Verifique se o diretório examples/ foi enviado com sua instalação — para checkouts do fonte, inicie o Imervue a partir da raiz do repositório.

O pet não fala quando clicado. Três verificações:

  1. Certifique-se de que o toggle Speech bubble on click está ligado (na aba ou no menu de clique direito).

  2. Se você carregou um script personalizado, verifique se o JSON faz parse — o rótulo de status da aba mostra o erro de carregamento.

  3. Se um clique em hit-area não fez nada, a área provavelmente não tem motion correspondente E o script não tem entrada hit_responses para esse id de área. Ou vincule uma motion à área na aba Puppet ou adicione o id da área aos hit_responses do script.

O checkbox de webcam tracking volta para o desligado. O rastreamento de webcam precisa de opencv-python e mediapipe instalados no mesmo ambiente Python em que o Imervue está rodando. Instale com pip install opencv-python mediapipe. Depois de instalar, alternar o checkbox deve abrir uma pequena janela de pré-visualização mostrando os marcos faciais detectados.

O pet não se oculta automaticamente durante apps em tela cheia. O detector de tela cheia faz polling da janela em primeiro plano a 1 Hz. No Windows ele usa a API Win32 GetWindowRect; no macOS / Linux não há um equivalente multi-plataforma confiável e ele faz no-op (o pet permanece visível). Para Windows: certifique-se de que Hide when other app is fullscreen está marcado e verifique se a janela em tela cheia realmente cobre ≥ 99 % do mesmo monitor do pet.

A posição do pet flutua para fora da tela entre inicializações. Isso acontece quando a tela em que o pet estava não está mais conectada na próxima inicialização (dock de notebook, segundo monitor desconectado). O pet cai automaticamente para o canto inferior direito da tela primária neste caso — arraste-o para onde você quiser e o próximo salvamento sobrescreverá a posição desatualizada.

Rotação e Inversão

Ação

Atalho

Menu

Rotacionar 90 ° horário

R

Botão direito > Modify > Rotate CW

Rotacionar 90 ° anti-horário

Shift + R

Botão direito > Modify > Rotate CCW

Inverter horizontal

–

Botão direito > Modify > Flip Horizontal

Inverter vertical

–

Botão direito > Modify > Flip Vertical

Rotação sem perdas (JPEG)

–

Botão direito > Lossless Rotate

Exportando Imagens

Exportação Única

Clique com o botão direito em uma imagem > Exportar / Salvar Como.

  • Escolha o formato: PNG, JPEG, WebP, BMP, TIFF

  • Ajuste a qualidade (para formatos com perdas)

  • Pré-visualize o tamanho estimado do arquivo

  • Escolha um local para salvar

Presets de Exportação

Para os alvos comuns de entrega que você não quer reajustar a cada vez, use Arquivo > Exportar com Preset. Um clique aplica o pipeline correto de redimensionamento, formato e qualidade:

Preset

Pipeline

Web 1600

Ajusta o lado maior para 1600 px, JPEG qualidade 85, sRGB; para uploads em blog / fórum onde a qualidade visual importa mais que a contagem de pixels.

Print 300 dpi

TIFF em resolução total / JPEG de alta qualidade com metadados de 300 dpi, saída com gerenciamento de cor para laboratórios e gráficas.

Instagram 1080

Recorte quadrado (1080 × 1080) ou retrato (1080 × 1350) com a proporção original preservada por dentro, JPEG qualidade 90.

Os presets se compõem com a sobreposição de marca d’água (abaixo) — habilite a marca d’água uma vez e cada saída de preset a carrega.

Sobreposição de Marca d’Água

Arquivo > Marca d'Água… abre um configurador de sobreposição não destrutivo. As configurações se aplicam apenas na exportação — os pixels originais no disco nunca são tocados.

  • Modo: texto ou imagem. Marcas d’água em imagem suportam PNG com alfa.

  • Posição: grade de 9 âncoras (cantos, bordas, centro).

  • Opacidade: 0 – 100 %.

  • Escala: porcentagem do lado maior exportado; a marca d’água se redimensiona automaticamente conforme você redimensiona para presets diferentes.

Exportação em Lote

Selecione várias imagens, depois clique com o botão direito > Exportação em Lote.

  • Conversão uniforme de formato

  • Definir largura / altura máximas (escala automática de proporção)

  • Controle de qualidade

  • Barra de progresso em tempo real

Criar GIF / Vídeo

Selecione várias imagens, depois clique com o botão direito > Criar GIF / Vídeo.

  • Saída GIF e MP4

  • Arraste para reordenar quadros

  • Defina quadros por segundo (FPS)

  • Dimensões personalizadas

  • Opção de loop

Reprodução de Animação

Ao abrir arquivos GIF, APNG ou WebP animados, a animação é reproduzida automaticamente.

Tecla

Ação

Space

Reproduzir / Pausar

,

Quadro anterior

.

Próximo quadro

]

Acelerar

[

Desacelerar

Comparação de Imagens

No modo de miniaturas, selecione 2 – 4 imagens, depois clique com o botão direito > Comparar Imagens.

A caixa de diálogo tem quatro abas:

Aba

Finalidade

Lado a lado

Exibir 2 ou 4 imagens simultaneamente; cada uma é redimensionada automaticamente em seu painel.

Sobreposição

Misturar duas imagens com um slider de alfa (0 → apenas A, 100 → apenas B). Requer exatamente 2 selecionadas.

Diferença

Visualização |A − B| por pixel com um slider de ganho (0,10× – 20×) para amplificar mudanças sutis.

Divisão A | B

Visualização dividida antes / depois com um divisor vertical arrastável. Arraste o handle para varrer entre as duas imagens; ideal para mostrar ajustes de receita de revelação ou comparar exportações. Requer exatamente 2 selecionadas.

Quando as duas imagens têm tamanhos diferentes, B é reamostrada para as dimensões de A com Lanczos. Imagens muito grandes são limitadas a 2048 px no lado maior internamente para que a sobreposição / diferença permaneçam interativas.

See also

Para comparação inline sem abrir uma caixa de diálogo, use Visão Dividida (Shift + S) ou Leitura em Página Dupla (Shift + D / Ctrl + Shift + D) descritas na seção Navegação.

Slideshow

Pressione S ou clique com o botão direito > Slideshow para iniciar um slideshow automático.

  • Intervalo ajustável por imagem

  • Transição opcional de fade entre imagens

Pesquisa

Pressione Ctrl + F ou / e digite uma palavra-chave para pesquisar imagens na pasta atual por nome de arquivo.

A pesquisa usa correspondência aproximada (fuzzy) com um ranqueamento em três níveis (prefixo > substring > subsequência) e destaque de substring nos resultados. Pressione Enter ou clique duas vezes para saltar para uma imagem.

Para saltar por índice de imagem em vez de nome, pressione Ctrl + G para a caixa de diálogo Ir Para.

Copiar e Colar

Ação

Método

Copiar imagem para a área de transferência

Ctrl + C no modo Deep Zoom

Colar imagem da área de transferência

Arquivo > Colar da Área de Transferência, ou Ctrl + V

Monitoramento automático da área de transferência

Arquivo > Anotar Automaticamente Imagens da Área de Transferência (alternar)

Note

Quando o monitoramento automático está habilitado, toda vez que uma nova imagem aparece na área de transferência (por exemplo, de uma ferramenta de captura de tela), o editor de anotações abre automaticamente.

Excluindo Imagens

Ação

Método

Excluir imagem atual

Pressione Delete

Excluir imagens selecionadas

Selecione várias, depois Delete ou clique com o botão direito > Excluir Selecionadas

As imagens são movidas para a Lixeira do sistema e podem ser recuperadas de lá.

Operações em Lote

No modo de miniaturas, selecione várias imagens e clique com o botão direito:

Recurso

Descrição

Renomear em Lote

Renomear usando templates: {name}, {n}, {ext}

Mover / Copiar

Mover ou copiar imagens para outra pasta

Rotacionar Todas

Rotacionar todas as imagens selecionadas de uma vez

Exportação em Lote

Converter formato e redimensionar em massa

Adicionar à Tag

Aplicar a mesma tag a todas as imagens selecionadas

Adicionar ao Álbum

Colocar todas as imagens selecionadas em um álbum

Histograma RGB

Pressione H no modo Deep Zoom para sobrepor um histograma RGB na imagem. Pressione novamente para ocultar.

Definir como Papel de Parede

Clique com o botão direito no modo Deep Zoom > Definir como Papel de Parede para definir a imagem atual como papel de parede da área de trabalho.

Suportado no Windows, macOS e Linux (GNOME).

Múltiplas Janelas

Arquivo > Nova Janela abre outra janela independente do Imervue. Cada janela pode navegar por uma pasta diferente.

Presets de Layout de Espaço de Trabalho

Arquivo > Espaços de Trabalho… captura a geometria atual da janela, o arranjo de docks / barras de ferramentas, tamanhos de splitter e pasta raiz ativa sob um nome — depois permite alternar entre layouts salvos da mesma forma que outros gerenciadores de fotos com suporte a XMP alternam Library / Develop / Export ou o Adobe Bridge alterna Metadata / Filmstrip. A caixa de diálogo suporta Salvar Atual, Carregar, Renomear e Excluir. Espaços de trabalho persistem em user_settings.json (sob a chave workspaces) e sobrevivem entre sessões.

Tip

Construa um espaço de trabalho Browse com a árvore e a grade de miniaturas visíveis, e um espaço Develop separado com o painel de revelação maximizado e a árvore colapsada. Um clique move sua janela inteira para a forma certa para cada tarefa.

Gestos de Touchpad

Gesto

Ação

Pinça

Zoom in / out no Deep Zoom (ancorado no centro da pinça)

Deslize horizontal

Imagem anterior / próxima

Associação de Arquivos (Windows)

Registrar o Imervue como visualizador de imagens no Windows Explorer:

  1. Arquivo > Associação de Arquivos > Registrar 'Open with Imervue'

  2. São necessários privilégios de administrador.

  3. Após o registro, clique com o botão direito em qualquer imagem no Explorer para ver a opção Open with Imervue.

Para remover: Arquivo > Associação de Arquivos > Remover associação de arquivos.

Sistema de Plugins

O Imervue suporta plugins para funcionalidade estendida.

Ação

Localização no Menu

Ver plugins instalados

Plugins > Gerenciar Plugins

Baixar novos plugins

Plugins > Baixar Plugins

Abrir pasta de plugins

Plugins > Abrir Pasta de Plugins

Recarregar plugins

Plugins > Recarregar Plugins

Idioma

Mude o idioma da interface a partir do menu Idioma:

  • Inglês (English)

  • Chinês Tradicional (繁體中文)

  • Chinês Simplificado (简体中文)

  • Coreano (한국어)

  • Japonês (日本語)

É necessária uma reinicialização após a mudança.

Referência de Atalhos de Teclado

Edição

Tecla

Ação

E

Abrir aba Modify

R

Rotacionar no sentido horário

Shift + R

Rotacionar no sentido anti-horário

Ctrl + Z

Desfazer

Ctrl + Shift + Z

Refazer

Delete

Excluir imagem

Organização

Tecla

Ação

0

Alternar favorito

1 – 5

Avaliar (pressione novamente para limpar)

F1 – F5

Rótulo de cor: vermelho / amarelo / verde / azul / roxo (pressione a mesma tecla para limpar)

P

Cull: Pick (marcar para manter)

Shift + X

Cull: Reject

U

Cull: Unflag

B

Alternar marcador

T

Gerenciador de Tags e Álbuns

Ferramentas e Sobreposições

Tecla

Ação

Ctrl + F / /

Pesquisa fuzzy com destaque de substring

Ctrl + C

Copiar imagem para a área de transferência

Ctrl + V

Colar da área de transferência

H

Histograma RGB

F8 / Ctrl + F8

Sobreposição OSD de informações / HUD de Debug (VRAM, cache, threads)

Shift + P

Visualização de pixel (≥ 400 % mostra grade de pixels e valor RGB sob o cursor)

Shift + M

Alternar modos de cor (Normal / Tons de Cinza / Inverter / Sépia)

S

Slideshow

Animação

Tecla

Ação

Space

Reproduzir / Pausar

,

Quadro anterior

.

Próximo quadro

[

Desacelerar

]

Acelerar

Gerenciamento de Biblioteca e Metadados

O Imervue mantém um índice baseado em SQLite em %LOCALAPPDATA%/Imervue/library.db (Windows) ou ~/.cache/imervue/library.db (POSIX) para pesquisa entre pastas, tags hierárquicas, álbuns inteligentes, hashes perceptuais, notas e flags de cull. Tudo abaixo fica em Extra Tools salvo indicação contrária. Na última versão, o menu está organizado em oito submenus agrupados por função — Batch, Library & Metadata, Views, Workflow, Export, Develop (Non-Destructive), Retouch & Transform e Multi-Image — então cada caminho abaixo é mostrado como Extra Tools > <submenu> > <tool>.

Pesquisa de Biblioteca

Extra Tools > Library & Metadata > Library Search permite adicionar uma ou mais pastas raiz a um índice global que é varrido em uma thread em segundo plano. Uma vez que uma raiz é indexada você pode consultá-la por extensão, largura/altura mínima, faixa de tamanho ou substring de nome e jogar os resultados no visualizador como um álbum virtual.

Álbuns Inteligentes

Extra Tools > Library & Metadata > Smart Albums persiste regras de filtro (extensões, dimensões mínimas, rótulos de cor, avaliação, favoritos, estado de cull, tags hierárquicas, substring de nome) sob um nome amigável. Reaplicar um álbum filtra a pasta ativa pelas regras salvas.

Pesquisa de Imagens Similares

Extra Tools > Library & Metadata > Find Similar Images executa um pHash DCT de 64 bits na imagem atual em deep-zoom (ou na primeira miniatura selecionada) e lista correspondências próximas do índice ordenadas pela distância de Hamming. Ajuste o spin Max distance para alargar ou apertar a rede.

Pesquisa Semântica (CLIP)

Extra Tools > Semantic Search permite digitar uma frase em linguagem natural (por exemplo “golden retriever na neve” ou “rua de neon à noite”) e retorna imagens classificadas da biblioteca indexada. Cada imagem é incorporada com um encoder visão/linguagem CLIP e armazenada junto com seu caminho; uma consulta de texto é incorporada no mesmo espaço vetorial e comparada por similaridade de cosseno.

Os embeddings são armazenados em cache em %LOCALAPPDATA%/Imervue/clip_cache.npz (Windows) ou ~/.cache/imervue/clip_cache.npz (POSIX) como um único arquivo .npz compacto para que a próxima inicialização pule a reincorporação. Apenas os caminhos que você varreu são consultáveis — use Scan Folder… dentro da caixa de diálogo para estender o índice.

Note

A Pesquisa Semântica requer os pacotes opcionais open_clip_torch e torch. Se não estiverem instalados, a entrada do menu explica o que está faltando e outros recursos continuam funcionando.

Auto-Tag

Extra Tools > Library & Metadata > Auto-Tag Images aplica tags heurísticas sob auto/... (photo / document / screenshot / landscape / portrait). Se onnxruntime e um modelo CLIP em models/clip_vit_b32.onnx estiverem disponíveis, também adiciona rótulos de conteúdo baseados em CLIP. Executa em uma thread de trabalho com uma barra de progresso em tempo real.

Tags Hierárquicas

Extra Tools > Library & Metadata > Hierarchical Tags gerencia tags em estrutura de árvore como animal/gato/british. Selecione uma tag para ver toda imagem abaixo daquele ramo (descendentes incluídos). Marque ou desmarque a seleção atual com um clique. Tags hierárquicas vivem no índice da biblioteca e são complementares ao sistema de tags planas no menu de clique direito.

Renomeação em Lote por Tokens

Extra Tools > Batch > Token Batch Rename abre uma tabela com pré-visualização ao vivo onde você digita um template como {date:yyyymmdd}_{camera}_{counter:04}{ext} e vê exatamente em que cada arquivo será renomeado. Conflitos são destacados para que nada seja sobrescrito. Tokens suportados: {name} {ext} {counter[:NN]} {date[:fmt]} {width} {height} {wxh} {size_kb} {camera} {year} {month} {day} {hour} {minute}.

Exportação de Metadados

Extra Tools > Library & Metadata > Export Metadata (CSV / JSON) escreve uma linha por imagem na visualização atual cobrindo EXIF, dimensões, rótulo de cor, avaliação, favorito, tags hierárquicas, estado de cull e notas. Útil para alimentar decisões de cull em uma planilha ou fluxo de trabalho externo.

Sidecar XMP (Interoperação com outros gerenciadores de fotos com suporte a XMP)

O Imervue pode ler e gravar arquivos sidecar XMP da Adobe (photo.jpg ↔ photo.xmp) para que avaliações, títulos, descrições, palavras-chave e rótulos de cor façam round-trip de forma limpa com outros gerenciadores de fotos com suporte a XMP, Bridge e outras ferramentas com suporte a XMP.

  • Importar XMP da imagem atual — extrai avaliação / título / palavras-chave / rótulo de cor do sidecar para o banco de dados interno.

  • Exportar XMP da imagem atual — grava a avaliação / título / palavras-chave / rótulo de cor atual em um sidecar ao lado da imagem.

  • Importar / exportar em lote — aplica a mesma operação à seleção ativa ou à pasta inteira.

O parser de XML usa defusedxml para que sidecars malformados ou maliciosos não possam disparar ataques XXE / billion-laughs. Se defusedxml não estiver instalado, as entradas de menu XMP ficam ocultas e nenhum sidecar é gravado.

A barra lateral EXIF também expõe uma tira de avaliação por estrelas clicável — a avaliação que ela define é a que a exportação XMP gravará.

Culling (Pick / Reject)

Flag de cull de três estados baseado em sinalização. Pressione P para escolher a imagem atual ou cada miniatura selecionada, Shift + X para rejeitar, U para desmarcar. Filtrar > Por Estado de Cull mostra apenas escolhidas, rejeitadas ou não marcadas. Extra Tools > Culling aplica o filtro via uma caixa de diálogo e também expõe um botão Excluir todas as rejeitadas que remove permanentemente os arquivos marcados do disco.

Bandeja de Staging

Extra Tools > Workflow > Staging Tray é uma cesta entre pastas. Adicione qualquer conjunto de miniaturas à bandeja (a lista sobrevive entre reinicializações), depois mova ou copie a bandeja inteira para uma pasta de destino com um clique. Útil para reunir escolhidas de várias sessões antes da exportação.

Gerenciador de Arquivos de Painel Duplo

Extra Tools > Workflow > Dual-Pane File Manager abre uma visualização com dois painéis e duas árvores. Escolha uma pasta em cada painel e mova/copie a seleção entre eles sem sair do Imervue.

Visualização de Linha do Tempo

Extra Tools > Views > Timeline View agrupa o conjunto atual de imagens por dia, mês ou ano (agrupado por data). A data é tirada do EXIF DateTimeOriginal quando presente, caso contrário do tempo de modificação do arquivo. Clique duas vezes em qualquer imagem para abri-la em Deep Zoom.

Arrastar para Apps Externos

Pressione e arraste de uma miniatura selecionada para soltar o arquivo no Explorer, Chrome, Discord ou qualquer app que aceite URLs de arquivo. A pré-visualização do arrasto é a miniatura.

Notas por Imagem

A barra lateral EXIF inclui uma caixa Notas de texto livre. A digitação salva automaticamente no índice da biblioteca após um pequeno debounce. As notas viajam com o caminho da imagem, então sobrevivem a re-varreduras de pasta.

Revelação Avançada e Composição

Curva de Tons

Extra Tools > Develop (Non-Destructive) > Tone Curve abre um editor de curvas com pontos arrastáveis e quatro canais (RGB, R, G, B). Clique com o botão esquerdo no canvas vazio para adicionar um ponto; arraste para mover; clique com o botão direito para excluir. Os pontos são interpolados com um spline cúbico monotônico e armazenados na receita da imagem, então a curva se aplica de forma não destrutiva no momento da renderização.

Aplicar LUT .cube

Extra Tools > Develop (Non-Destructive) > Apply .cube LUT permite escolher qualquer arquivo .cube da Adobe (1D ou 3D, até 64³). A LUT é parseada com um lru_cache chaveado por caminho + mtime, avaliada com interpolação trilinear, e misturada contra o original via um slider de intensidade. O caminho da LUT e a intensidade ficam na receita.

Cópias Virtuais

Extra Tools > Workflow > Virtual Copies dá a cada imagem snapshots nomeados de receitas. Capture a edição atual, continue experimentando e volte para qualquer variante anterior depois. As variantes ficam ao lado da receita master na loja de receitas e sobrevivem ao reset do master para a identidade.

Mesclagem HDR

Extra Tools > Multi-Image > HDR Merge combina duas ou mais exposições com bracket em uma única imagem via a fusão de exposição Mertens do OpenCV. A caixa opcional “Align exposures” executa cv2.AlignMTB primeiro para compensar trepidação ao segurar a câmera. A saída é salva em um arquivo escolhido pelo usuário — não toca nenhuma imagem fonte.

Stitch de Panorama

Extra Tools > Multi-Image > Panorama Stitch envolve a API de alto nível Stitcher do OpenCV. Escolha o modo Panorama para paisagens / cityscapes ou o modo Scans para documentos planos e obras de arte. As bordas pretas produzidas pelo warp podem ser auto-recortadas.

Empilhamento de Foco

Extra Tools > Multi-Image > Focus Stacking funde múltiplos disparos tirados em diferentes distâncias de foco. Para cada pixel o algoritmo escolhe qualquer quadro de entrada que tem a maior nitidez local (variância Laplaciana), depois suaviza a máscara de seleção com uma mistura gaussiana para evitar emendas. O alinhamento ECC fica ligado por padrão para pequenos offsets ao segurar a câmera.

Pincel de Cura

Extra Tools > Retouch & Transform > Healing Brush mostra a imagem atual em até 720 px no lado maior. Clique com o botão esquerdo para adicionar uma mancha circular; clique com o botão direito em uma mancha existente para removê-la; o slider de raio define o tamanho da nova mancha. Ao aplicar, o inpainting do OpenCV (Telea para velocidade, Navier-Stokes para mistura mais suave) preenche cada região mascarada a partir dos pixels circundantes e o resultado é salvo em um novo arquivo.

Correção de Lente

Extra Tools > Retouch & Transform > Lens Correction expõe quatro sliders pure-numpy: distorção radial k1 (barril / pincushion), elevação de vinheta, e escala radial de aberração cromática por canal para vermelho e azul. A imagem corrigida é salva como um novo arquivo — a correção de lente não faz parte da receita porque a forma da saída pode mudar.

Visualização de Mapa

Extra Tools > Views > Map View plota cada imagem geotagueada na biblioteca atual em um mapa interativo Leaflet + OpenStreetMap (requer PySide6.QtWebEngineWidgets). Sem WebEngine, a caixa de diálogo recai para uma lista simples de entradas (path, lat, lon) para que o recurso permaneça utilizável em instalações mínimas.

Visualização de Calendário

Extra Tools > Views > Calendar View mostra um QCalendarWidget com dias destacados quando as fotos foram tiradas naquele dia (EXIF DateTimeOriginal → DateTimeDigitized → mtime do arquivo). Selecionar uma data lista suas imagens; clique duas vezes para abrir uma no visualizador principal.

Detecção Facial

Extra Tools > Retouch & Transform > Face Detection executa o cascade Haar de detecção de faces frontais do OpenCV na imagem atual e desenha cada detecção como um retângulo. Clique duas vezes em uma linha da lista para digitar o nome de uma pessoa; ao salvar, as tags são gravadas no blob extra['face_tags'] da receita. A detecção é uma técnica clássica — a precisão é adequada para “mostre-me os rostos” mas não substitui o reconhecimento moderno baseado em CNN.

Máscaras de Ajuste Local

Extra Tools > Develop (Non-Destructive) > Local Adjustment Masks coloca máscaras de pincel, radial ou gradiente linear sobre a imagem. Cada máscara carrega sua própria exposição, brilho, contraste, saturação, temperatura, deltas de matiz mais um slider de pluma. As máscaras são salvas em recipe.extra['masks'] e aplicadas de forma não destrutiva no carregamento, então o arquivo subjacente nunca é tocado.

Tonalização Dividida

Extra Tools > Develop (Non-Destructive) > Split Toning aplica matizes distintos a sombras e realces com saturação por região e um pivô de balanço. Armazenado em recipe.extra['split_toning'] e aplicado após a curva de tons no pipeline de revelação.

Carimbo de Clonagem

Extra Tools > Retouch & Transform > Clone Stamp copia um patch fonte com pluma para um destino — o complemento de borda dura do pincel de cura. Shift+clique define a fonte, um clique normal carimba, clique com o botão direito desfaz. O resultado é gravado em um novo arquivo para que o original permaneça intacto.

Recorte / Endireitar

Extra Tools > Retouch & Transform > Crop / Straighten combina um retângulo de recorte normalizado (0..1) com um ângulo de endireitamento arbitrário. A saída é auto-recortada para o maior retângulo interno para que fotos rotacionadas não tenham cantos pretos.

Endireitamento Automático

Extra Tools > Retouch & Transform > Auto-Straighten detecta o horizonte ou linhas verticais dominantes via detecção de linhas de Hough e propõe uma rotação. Um clique aplica o endireitamento; você pode ajustar o ângulo primeiro se a auto-detecção escolher a referência errada.

Redução de Ruído / Nitidez

Extra Tools > Retouch & Transform > Noise Reduction / Sharpening aplica uma redução de ruído bilateral (preservando bordas) seguida de um sharpen unsharp-mask. “Apenas luminância” mantém o ruído de cor intacto mas achata a granulação sem borrar bordas de chroma.

Céu / Fundo

Extra Tools > Retouch & Transform > Sky / Background substitui o céu detectado por um gradiente ou remove o fundo para transparente / branco. Quando rembg (U²-Net) está instalado, a máscara de primeiro plano vem da rede de segmentação; caso contrário, a regra heurística HSV é usada.

Soft Proof

Extra Tools > Develop (Non-Destructive) > Soft Proof carrega um perfil ICC, converte a imagem através dele e de volta, e destaca em magenta os pixels que clipparam durante o round-trip — uma verificação rápida fora-de-gamut antes de imprimir.

Geotag GPS

Extra Tools > Library & Metadata > GPS Geotag lê quaisquer tags GPS EXIF existentes e permite editar ou definir novas coordenadas em graus decimais. Requer piexif instalado; grava em JPEG no local.

Layout de Impressão

Extra Tools > Export > Print Layout compõe múltiplas imagens em um PDF de várias páginas com tamanho de página, orientação, grade, margens, sarjeta e marcas de corte configuráveis. Requer reportlab.

Uso na Linha de Comando

imervue                        # Iniciar normalmente
imervue /caminho/para/imagem   # Abrir uma imagem específica
imervue /caminho/para/pasta    # Abrir uma pasta específica
imervue --debug                # Habilitar modo debug
imervue --software_opengl      # Usar renderização por software (quando a GPU não é suportada)

Servidor MCP

O Imervue inclui um servidor Model Context Protocol embutido que permite que assistentes de IA chamem os helpers de lógica pura do projeto sem uma GUI rodando. Inicie-o com:

python -m Imervue.mcp_server

O servidor é livre de Qt e carrega apenas o que cada ferramenta precisa no momento da chamada.

Ferramentas Disponíveis

Ferramenta

Finalidade

list_images

Lista arquivos de imagem em uma pasta (caminho, tamanho, mtime). Passe recursive=true para percorrer subpastas.

read_image_metadata

Dimensões, formato, tags EXIF e campos de sidecar XMP para uma imagem. Dados ausentes são reportados como o valor vazio apropriado em vez de gerar exceção.

read_xmp_tags

Caminho rápido que lê apenas o sidecar XMP — avaliação, rótulo de cor, palavras-chave, título, descrição.

convert_format

Converte uma imagem para outro formato. O formato de destino é inferido pelo sufixo de destino (png / jpg / jpeg / webp / tiff / bmp). O parâmetro opcional quality (1–100) se aplica a JPEG/WebP.

puppet_from_png

Constrói um rig .puppet a partir de um PNG usando o auto-mesh do plugin puppet. Inicializa o catálogo padrão de parâmetros Cubism para que o rig seja imediatamente dirigível.

puppet_inspect

Abre um arquivo .puppet e retorna um inventário estruturado: drawables, deformadores, parâmetros, motions, expressões, áreas de hit, partes, blends de parâmetro e rigs de física.

Todas as ferramentas retornam payloads serializados em JSON dentro do envelope content / text do MCP; payloads estruturados podem ser parseados de volta a partir do campo text no lado do cliente.

Claude Code (Nível de Projeto)

O repositório inclui um .mcp.json em nível de projeto na raiz do repositório:

{
  "mcpServers": {
    "imervue": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "Imervue.mcp_server"]
    }
  }
}

Abrir qualquer subdiretório do repositório no Claude Code descobre automaticamente este servidor. O Claude Code pergunta antes de habilitar servidores de projeto na primeira vez — aceite o prompt para usá-lo.

Claude Desktop

Adicione a mesma entrada à sua configuração do Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Use um diretório de trabalho absoluto ou ative um virtualenv no qual o Imervue esteja instalado; a invocação python deve resolver para um interpretador capaz de import Imervue.

Superfície do Protocolo

O servidor implementa o transporte JSON-RPC 2.0 via stdio do MCP versão 2025-03-26:

  • initialize — handshake; anuncia capabilities.tools.

  • tools/list — enumera as ferramentas registradas com suas definições de entrada JSON-Schema.

  • tools/call — invoca uma ferramenta com {"name", "arguments"}; os resultados voltam dentro do array content.

  • notifications/* — aceitas silenciosamente (sem resposta).

A implementação está em Imervue/mcp_server/:

  • server.py — loop de protocolo + registro de ferramentas.

  • tools.py — funções handler e as definições de ferramenta padrão.

  • __main__.py — ponto de entrada python -m Imervue.mcp_server.

Ferramentas customizadas podem ser registradas construindo MCPServer manualmente, chamando MCPServer.register() e alimentando mensagens através de MCPServer.handle_message() (ou conduzindo o loop stdio com o helper run() embutido).