# OpenPose Studio for ComfyUI 🤸
OpenPose Studio é uma extensão avançada para ComfyUI que permite criar, editar, visualizar e organizar poses OpenPose com uma interface prática e fluida. Ela facilita o ajuste visual de keypoints, o salvamento e carregamento de arquivos de poses, a navegação por presets e galerias de poses, o gerenciamento de coleções, a fusão de múltiplas poses e a exportação de dados JSON limpos para uso com ControlNet e outros workflows guiados por poses.
---
## Índice
- ✨ [Funcionalidades](#funcionalidades)
- 📱 [Interface móvel responsiva](#interface-móvel-responsiva)
- 📦 [Instalação](#instalação)
- 🎯 [Uso](#uso)
- 🖐️ [Edição de mãos](#edição-de-mãos)
- 🔧 [Nodes](#nodes)
- ⌨️ [Controles e atalhos do editor](#controles-e-atalhos-do-editor)
- 📋 [Especificações de formato](#especificações-de-formato)
- 🖼️ [Galeria e gerenciamento de poses](#galeria-e-gerenciamento-de-poses)
- 🔀 [Pose Merger](#pose-merger)
- 🎨 [Render](#render)
- 🖼️ [Referência de fundo](#background-reference)
- 🗺️ [Areas Input](#areas-input)
- ⚠️ [Limitações conhecidas](#limitações-conhecidas)
- 🔍 [Solução de problemas](#solução-de-problemas)
- 🤝 [Contribuindo](#contribuindo)
- 💙 [Financiamento e suporte](#financiamento-e-suporte)
- 📄 [Licença](#licença)
---
## Funcionalidades
✨ **Capacidades principais**
- Edição de keypoints OpenPose em tempo real com feedback visual
- Edição individual de keypoints das mãos em um editor focado e ampliado
- Motor de renderização Canvas nativo moderno (mais rápido, mais suave, menos peças móveis)
- UX de edição interativa: seleção ativa clara + pré-seleção de pose no hover
- Transformações restritas para que keypoints não fujam dos limites do canvas
- Importação/exportação JSON para poses individuais e coleções de poses
- Exportação JSON padrão OpenPose (portátil para outras ferramentas)
- Compatibilidade JSON legacy (pode carregar e editar corretamente JSON não-padrão mais antigos)
✨ **Funcionalidades avançadas**
- **Render Toggles**: Renderizar opcionalmente Body / Hands / Face
- **Pose Gallery**: Navegar e visualizar poses de `poses/`
- **Pose Collections**: Arquivos JSON multi-pose exibidos como poses individualmente selecionáveis
- **Pose Merger**: Combinar múltiplos arquivos JSON em coleções organizadas
- **Quick Cleanup Actions**: Remover keypoints Face e/ou keypoints de Mão esquerda/direita quando presentes
- **Optional Cleanup on Export**: Remover keypoints Face e/ou Hands ao exportar pacotes de poses
- **Background Overlay System**: Modos Contain/Cover selecionáveis com controle de opacidade
- **Undo**: Histórico completo de edição durante a sessão
✨ **Manipulação de dados**
- Descoberta automática de arquivos de pose em `poses/` (incluindo subdiretórios)
- Validação e recuperação de erros para arquivos JSON malformados
- Suporte a poses parciais (subconjunto de keypoints body)
- Coordenadas em espaço de pixel correspondendo aos arquivos de pose para compatibilidade perfeita
✨ **UI e integração**
- Layout totalmente responsivo: adapta-se em tempo real a qualquer tamanho de janela e permanece centralizado
- Escalonamento automático quando o canvas não caberia na tela
- Visuais aprimorados do canvas: grade de fundo + eixos centrais estilizados como no Blender
- Persistência entre reinicializações: modo de visualização da galeria + configurações de overlay de fundo restauradas no lançamento
- Integrações nativas do ComfyUI: toasts + diálogos (com fallback seguro)
## Interface móvel responsiva
O OpenPose Studio é totalmente responsivo e compatível com controles por toque em navegadores móveis. O Editor mantém o canvas utilizável em telas estreitas, apresenta as ferramentas de Preset e COCO Keypoints como visualizações focadas e oferece uma Gallery compacta com várias densidades de miniaturas.
Edição no canvas, controles de Preset, gerenciamento de keypoints ausentes e visualização Small Icons da Gallery no Android.
---
Se você tiver uma ideia para uma nova funcionalidade, adoraria ouvi-la — podemos ser capazes de implementá-la rapidamente. Envie feedback, ideias ou sugestões pela página de Issues do repositório: https://github.com/andreszs/comfyui-openpose-studio/issues
## Instalação
### Requisitos
- ComfyUI (build recente)
- Python 3.10+
### Opção 1: Extension Manager nativo (recomendada)
1. Abra o **Extension Manager** nativo do ComfyUI e depois o **Nodes Manager**.
2. Pesquise `openpose-studio` e selecione **OpenPose Studio**.
3. Clique em **Install** e reinicie o ComfyUI quando a instalação terminar.
### Opção 2: Instalação manual
Abra um terminal em `ComfyUI/custom_nodes/` e clone o repositório:
```bash
git clone https://github.com/andreszs/comfyui-openpose-studio.git
```
Reinicie o ComfyUI depois de clonar o repositório.
### Verificar a instalação
Confirme que **OpenPose Studio** aparece no menu de nodes em `image > OpenPose Studio`.
---
## Uso
### Workflow básico
1. Adicionar o node **OpenPose Studio** ao seu workflow
2. Clicar no canvas de pré-visualização do node para abrir a UI do editor
3. Selecionar uma pose dos presets ou da galeria para inserir no canvas
4. Ajustar os keypoints arrastando-os no canvas
5. Clicar em **Apply** para renderizar a pose. Isso criará o JSON serializado no node.
6. Conectar a saída `image` aos nodes de imagem subsequentes
7. Conectar a saída `kps` aos nodes compatíveis com ControlNet/OpenPose
### Pré-visualização do editor
### Edição de mãos
As mãos OpenPose importadas podem ser transformadas como um grupo ou refinadas keypoint por keypoint. Selecione uma mão no canvas para exibir sua caixa de transformação e use os controles ao redor para redimensionar, girar, espelhar ou abrir o editor focado de mãos.
Você também pode abrir o editor focado diretamente pelo ícone de lápis ao lado de **Left hand** ou **Right hand** na barra lateral. Nessa visualização, arraste os keypoints 1–20 para ajustar os dedos; o keypoint 0 permanece bloqueado como âncora da mão. Passar o mouse sobre uma entrada da barra lateral destaca o ponto correspondente. Use o botão de confirmação para aplicar toda a sessão como uma única alteração que pode ser desfeita, ou o botão de fechar ou **Escape** para descartá-la.
---
## Nodes
### OpenPose Studio
**Categoria:** `image`
- **Entrada:** `Pose JSON` (STRING) — JSON padrão estilo OpenPose.
- **Entradas opcionais:**
- `areas` (`CONDITIONING_AREAS`) — dados de overlay de áreas; conectar a saída `areas_out` de um node [Conditioning Pipeline (Combine)](https://github.com/andreszs/comfyui-lora-pipeline) para visualizar as regiões de condicionamento no canvas
- **Opções:**
- `render body` — incluir body na imagem de pré-visualização/saída renderizada
- `render hands` — incluir hands na imagem de pré-visualização/saída renderizada (se presentes no JSON)
- `render face` — incluir face na imagem de pré-visualização/saída renderizada (se presente no JSON)
- **Saídas:**
- `IMAGE` — Visualização renderizada da pose como imagem RGB (float32, intervalo 0-1)
- `JSON` — JSON estilo OpenPose com dimensões do canvas e array people contendo dados de keypoints
- `KPS` — Dados de keypoints no formato POSE_KEYPOINT, compatível com ControlNet
- **UI:** Clicar na pré-visualização do node para abrir o editor interativo. Usar o botão **open editor** (ícone de lápis) para editar a pose diretamente.
#### Captura de tela do node
---
## Controles e atalhos do editor
### Atalhos de teclado
| Controle | Ação |
|---------|--------|
| **Enter** | Aplicar pose e fechar o editor |
| **Escape** | Cancelar e descartar alterações |
| **Ctrl+Z** | Desfazer última ação |
| **Ctrl+Y** | Refazer última ação desfeita |
| **Delete** | Remover keypoint selecionado |
### Interações com o canvas
- **Clique**: Selecionar keypoint
- **Arrastar**: Mover keypoint para nova posição
- **Scroll**: Zoom in/out no canvas (TO-DO)
### Background Reference
Carregar imagens de referência (ex. guias de anatomia, referências fotográficas) como sobreposições não-destrutivas durante a edição de poses. Usar o modo **Contain** para ajustar imagens dentro do canvas ou o modo **Cover** para preencher o canvas. Ajustar a opacidade conforme necessário.
- **Load Image**: Importar imagem de referência do disco
- **Contain/Cover**: Escolher modo de escalonamento
- **Opacity**: Ajustar transparência (0-100%)
> [!NOTE]
> Imagens de fundo persistem durante a sessão do ComfyUI mas **não** são salvas nos workflows.
### Areas Input
A entrada **areas** é uma conexão **opcional** que sobrepõe os limites das áreas de condicionamento no canvas durante a edição de poses.
Conecte a saída `areas_out` do node [**Conditioning Pipeline (Combine)**](https://github.com/andreszs/comfyui-lora-pipeline) do repositório [ComfyUI-LoRA-Pipeline](https://github.com/andreszs/comfyui-lora-pipeline) para visualizar quais regiões cada área visa enquanto posiciona suas poses.
Cada área é exibida como um badge rotulado no canvas. Clique em qualquer badge para **habilitar ou desabilitar** essa área individualmente, permitindo que você se concentre nas regiões relevantes para a pose atual.
Essa combinação é particularmente útil ao construir workflows com múltiplos personagens: o [ComfyUI-LoRA-Pipeline](https://github.com/andreszs/comfyui-lora-pipeline) gerencia o condicionamento por área e a atribuição de LoRA, enquanto o OpenPose Studio mantém o posicionamento preciso das poses dentro de cada região. O resultado é uma configuração direta e não destrutiva onde LoRAs por área e por pose podem ser aplicados simultaneamente sem interferência. Se você ainda não conhece o condicionamento baseado em áreas, a extensão [ComfyUI-LoRA-Pipeline](https://github.com/andreszs/comfyui-lora-pipeline) foi projetada exatamente para esse tipo de workflow e se integra bem com este node.
Para um exemplo real dos três repositórios trabalhando juntos — condicionamento por áreas, controle de OpenPose e aplicação de estilos em camadas — veja este [guia passo a passo do workflow](https://www.andreszsogon.com/building-a-multi-character-comfyui-workflow-with-area-conditioning-openpose-control-and-style-layering/).
---
## Especificações de formato
Este editor oferece suporte completo à edição **OpenPose COCO-18 (body)** e à edição individual de **keypoints de mãos OpenPose**. Os keypoints de face são preservados e renderizados, mas continuam como dados *pass-through* e atualmente não podem ser editados individualmente.
### Keypoints OpenPose COCO-18 (body)
COCO-18 usa **18 keypoints body**. A pose é armazenada como um array plano chamado `pose_keypoints_2d` com o padrão:
`[x0, y0, c0, x1, y1, c1, ...]`
Onde cada keypoint tem:
- `x`, `y`: coordenadas em pixels no canvas
- `c`: confiança (comumente `0..1`; `0` pode ser usado para pontos "ausentes")
Ordem dos keypoints (índice → nome):
| Índice | Nome |
|------:|------|
| 0 | Nariz |
| 1 | Pescoço |
| 2 | Ombro direito |
| 3 | Cotovelo direito |
| 4 | Pulso direito |
| 5 | Ombro esquerdo |
| 6 | Cotovelo esquerdo |
| 7 | Pulso esquerdo |
| 8 | Quadril direito |
| 9 | Joelho direito |
| 10 | Tornozelo direito |
| 11 | Quadril esquerdo |
| 12 | Joelho esquerdo |
| 13 | Tornozelo esquerdo |
| 14 | Olho direito |
| 15 | Olho esquerdo |
| 16 | Orelha direita |
| 17 | Orelha esquerda |
> [!NOTE]
> **COCO** refere-se à convenção/nomenclatura de dataset *Common Objects in Context* amplamente usada em estimação de pose. "COCO-18" aqui significa o layout body do OpenPose com 18 keypoints.
### Estrutura JSON mínima
Um JSON típico estilo OpenPose para uma pose individual inclui dimensões do canvas e uma entrada `people` com `pose_keypoints_2d`:
```json
{
"canvas_width": 512,
"canvas_height": 512,
"people": [
{
"pose_keypoints_2d": [0, 0, 0, 0, 0, 0 /* ... 18 * 3 values total ... */]
}
]
}
```
> [!NOTE]
> O editor pode lidar com poses parciais (alguns keypoints ausentes). Pontos ausentes são tipicamente representados como 0,0,0. Você também pode deletar keypoints distais usando o Pose Editor.
### Leitura adicional
- História e contexto: "What is OpenPose — Exploring a milestone in pose estimation" — um artigo acessível explicando como o OpenPose foi introduzido e seu impacto na estimação de pose: https://www.ultralytics.com/blog/what-is-openpose-exploring-a-milestone-in-pose-estimation
### Formato JSON: Padrão vs Legacy
- **OpenPose Studio:** lê/escreve **JSON padrão estilo OpenPose** e também aceita JSON legacy não-padrão antigo.
Notas práticas:
- Colar JSON padrão no node OpenPose Studio renderiza a pré-visualização imediatamente.
---
## Galeria e gerenciamento de poses
### Visão geral
A aba **Gallery** fornece navegação visual de todas as poses disponíveis com miniaturas de pré-visualização ao vivo. Descobre e organiza poses automaticamente sem configuração manual.
### Modos de visualização
A Gallery suporta quatro modos de exibição:
- **Large** — pré-visualizações maiores para seleção visual rápida
- **Medium** — tamanho e densidade de pré-visualização equilibrados
- **Small** — grade densa de ícones otimizada para layouts estreitos e móveis
- **Tiles** — grade compacta com metadados extras (ex. **tamanho do canvas**, **contagem de keypoints** e outros detalhes da pose)
### Funcionalidades
- **Auto-discovery**: Varre o diretório `poses/` na inicialização
- **Nested organization**: Nomes de subdiretórios tornam-se rótulos de grupo
- **Live preview**: Renderização de miniaturas ao vivo para cada pose
- **Search/filter**: Encontrar poses por nome ou grupo
- **One-click load**: Selecionar uma pose para carregá-la no editor
### Tipos de arquivo suportados
- **Single-pose JSON**: Arquivos JSON OpenPose individuais
- **Pose Collections**: Arquivos JSON multi-pose (cada pose exibida separadamente)
- **Nested directories**: Poses em subdiretórios automaticamente agrupadas
### Comportamento determinístico
Ordenação e descoberta da galeria são totalmente determinísticas:
- Sem embaralhamento aleatório
- Classificação alfabética consistente
- Poses raiz listadas primeiro, depois poses agrupadas
- Recarregamento imediato de todas as poses JSON ao abrir a janela do Editor.
---
## Pose Merger
### Propósito
A aba **Pose Merger** consolida múltiplos arquivos JSON de poses individuais em arquivos de coleção de poses organizados. Isso é útil para:
- Converter grandes bibliotecas de poses em arquivos únicos
- Limpar dados de poses (remover keypoints face/hand)
- Reorganizar e renomear poses
- Distribuir pacotes de poses eficientemente
### Workflow
1. **Add Files**: Carregar arquivos JSON individuais ou de coleção
2. **Preview**: Cada pose exibida com miniatura
3. **Configure**: Opcionalmente excluir componentes face/hand
4. **Export**: Salvar como coleção combinada ou arquivos individuais
### Capacidades principais
| Funcionalidade | Caso de uso |
|---------|----------|
| **Load Multiple Files** | Importação em massa do sistema de arquivos |
| **Component Filtering** | Remover dados desnecessários de face/hand |
| **Collection Expansion** | Extrair poses de coleções existentes |
| **Batch Renaming** | Atribuir nomes significativos durante o export |
| **Selective Export** | Escolher quais poses incluir |
### Opções de saída
- **Combined Collection**: JSON único com todas as poses
- **Individual Files**: Um arquivo por pose (para compatibilidade)
Ambos os formatos de saída são automaticamente detectados pela Gallery e pelo Pose Selector.
---
## Render
O módulo **Render** permite personalizar como o stickman do OpenPose é renderizado quando o workflow é executado. Ele inclui controles de estilo para body, hands e face, como largura de linha, raio de keypoint e cor de keypoint para hands/face.
As configurações de Render são salvas localmente no local storage deste navegador, não no workflow. Alterá-las afeta as próximas execuções do workflow.
---
## Limitações conhecidas
> [!NOTE]
> Nodes 2.0 é suportado. Se o canvas de preview ou o botão do editor estiver ausente, verifique o cache do navegador, o carregamento do frontend e os logs de instalação.
### Limitações atuais e alternativas
1. **Edição de Face**
- Os keypoints de face são preservados e renderizados, mas atualmente não podem ser editados individualmente no canvas.
2. **Consistência de resolução**
- Problema: Pose Merger não unifica automaticamente a resolução em exports de coleções
- Status: Requer implementação cuidadosa para evitar recorte
- Alternativa: Pré-escalar as poses para a resolução alvo antes de importar
3. **Compatibilidade com Nodes 2.0**
- Status: Suportado nas versões atuais.
- Nota: Se a UI do editor não aparecer, as causas mais prováveis são cache antigo do navegador, falha ao carregar módulos do frontend ou instalação incompleta.
- Diagnóstico: Reinicie o ComfyUI completamente, force a atualização do navegador e verifique o console do navegador junto com o log de inicialização do ComfyUI.
### Recuperação de erros
O plugin inclui tratamento defensivo de erros:
- Arquivos JSON inválidos são ignorados silenciosamente na Gallery
- Erros de renderização retornam imagens em branco em vez de crashar
- Metadados ausentes utilizam padrões seguros
- Keypoints malformados são filtrados durante a renderização
---
## Solução de problemas
### Problemas comuns e soluções
**Poses não aparecem na Gallery**
```
✓ Confirmar que os arquivos existem no diretório poses/
✓ Verificar se o JSON é válido (usar validador JSON online)
✓ Verificar se a extensão do arquivo é .json (diferencia maiúsculas/minúsculas no Linux)
✓ Reiniciar o ComfyUI para acionar a descoberta
✓ Verificar o console do navegador (F12) por mensagens de erro
```
**Importação JSON falha**
```
✓ Validar a estrutura JSON (deve ter "pose_keypoints_2d" ou equivalente)
✓ Garantir que as coordenadas são números válidos, não strings
✓ Confirmar mínimo de 18 keypoints para poses body
✓ Verificar sequências de escape malformadas no JSON
```
**Imagem de saída em branco**
```
✓ Verificar se a pose está selecionada e contém keypoints válidos
✓ Verificar as dimensões do canvas (largura/altura) razoáveis (100-2048px)
✓ Clicar em Apply para renderizar após fazer alterações
✓ Verificar por valores NaN ou infinitos nas coordenadas
```
**Background reference não persiste**
```
✓ Habilitar cookies/armazenamento de terceiros no navegador
✓ Verificar configurações de localStorage do navegador
✓ Tentar modo incógnito para isolar o problema
✓ Limpar cache do navegador e tentar novamente
```
**Node não aparece no ComfyUI**
```
✓ Verificar o local do clone: ComfyUI/custom_nodes/comfyui-openpose-studio
✓ Verificar se __init__.py existe e importa corretamente
✓ Reiniciar o ComfyUI completamente (não apenas recarregar a página)
✓ Verificar o console do ComfyUI por erros de importação
```
---
## Contribuindo
Para diretrizes de contribuição, diretrizes de pull request, detalhes de arquitetura e informações de desenvolvimento, ver [CONTRIBUTING.md](../CONTRIBUTING.md). Se usar um agente de IA para auxiliar no desenvolvimento, certifique-se de que ele leia [AGENTS.md](../AGENTS.md) antes de fazer qualquer alteração no código.
---
## Financiamento e suporte
### Por que seu suporte é importante
Este plugin é desenvolvido e mantido de forma independente, com uso regular de **agentes de IA pagos** para acelerar depuração, testes e melhorias de qualidade de vida. Se você o achar útil, o suporte financeiro ajuda a manter o desenvolvimento avançando constantemente.
Sua contribuição ajuda a:
* Financiar ferramentas de IA para correções mais rápidas e novas funcionalidades
* Cobrir manutenção contínua e trabalho de compatibilidade nas atualizações do ComfyUI
* Prevenir desacelerações no desenvolvimento quando os limites de uso são atingidos
> [!TIP]
> Não pode doar? Uma estrela GitHub ⭐ ainda ajuda muito melhorando a visibilidade e alcançando mais usuários.
### 💙 Apoiar este projeto
Prefere escanear? Mostrar QR codes
Ko-fi
|
PayPal
|
USDC (Arbitrum) ⚠️
|
Mostrar endereço USDC
```text
0xe36a336fC6cc9Daae657b4A380dA492AB9601e73
```
> [!WARNING]
> Enviar USDC somente na Arbitrum One. Transferências enviadas em qualquer outra rede não chegarão e podem ser permanentemente perdidas.
---
## Licença
Licença MIT — ver o arquivo [LICENSE](../LICENSE) para o texto completo.
**Resumo:**
- ✓ Gratuito para uso comercial
- ✓ Gratuito para uso privado
- ✓ Modificar e distribuir
- ✓ Incluir licença e aviso de copyright
---
## Recursos adicionais
### Projetos relacionados
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) - Framework principal
- [comfyui_controlnet_aux](https://github.com/Kosinkadink/ComfyUI-Advanced-ControlNet) - Suporte ControlNet
- [OpenPose](https://github.com/CMU-Perceptual-Computing-Lab/openpose) - Detecção de pose original
### Documentação
- [ComfyUI Custom Nodes Guide](https://github.com/comfyanonymous/ComfyUI/blob/main/docs/)
- [OpenPose Models & Keypoints](https://github.com/CMU-Perceptual-Computing-Lab/openpose/blob/master/doc/02_Output.md)
- [Canvas 2D API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) - Motor de renderização
### Guias de solução de problemas
- [ComfyUI Installation Issues](https://github.com/comfyanonymous/ComfyUI/wiki/Installation)
- [Node Registration & Loading](https://github.com/comfyanonymous/ComfyUI/blob/main/docs/CONTRIBUTING.md)
- [Browser Developer Tools](https://developer.chrome.com/docs/devtools/)
---
**Mantido por:** andreszs
**Status:** Desenvolvimento ativo
