> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/image-widget.md).
# Widget de Imagem
Fixe leituras de sensores em tempo real em qualquer imagem — planta, foto do local, esquema do equipamento — com o Widget de Imagem.
O widget de imagem transforma uma imagem num dashboard em tempo real. Carregue uma imagem — e ela pode ser **qualquer imagem**: uma planta, um esquema de equipamento, um diagrama do local, uma foto de um edifício, uma foto de uma peça de equipamento, como os silos acima — e depois fixe nela leituras numéricas em tempo real, cada uma exatamente onde o respetivo sensor se encontra.
Essa é a ideia principal: deixa de ler uma lista de nomes de dispositivos e passa a olhar para o local ou máquina reais e ver o que cada parte está a fazer neste momento. Um gestor de fábrica olha para a foto dos silos e vê qual tanque está a ficar com pouco nível; um engenheiro de manutenção olha para um esquema de equipamento e vê qual componente está fora da tolerância.
Carregue um ficheiro de imagem suportado — PNG ou JPG — de qualquer local, objeto ou sistema que queira monitorizar. Cada leitura fixada mostra o seu valor atual, a sua unidade e um ícone, e a sua cor muda à medida que as condições são acionadas, para que o estado seja visível em toda a imagem à primeira vista.
## Configurar um widget de imagem
Aqui está uma configuração completa para um caso real — monitorizar uma fila de silos de grãos a partir de uma única foto do local. Um sensor de nível em cada silo reporta o seu enchimento em percentagem. Este é um exemplo: a imagem pode ser qualquer coisa, e os passos são os mesmos.
1. Abra o painel no modo de edição e clique **Widget de imagem** no seletor de widgets. O painel de definições abre — e, ao contrário dos outros widgets, o **Aparência** separador abre primeiro, porque tem de carregar a imagem antes de poder colocar qualquer coisa nela.
2. Introduza um nome para o widget — por exemplo, "Níveis dos silos".
3. O widget começa com uma camada, **Camada 1**, já criada. Dê-lhe um **nome da camada** ("Pátio dos silos") claro e carregue a imagem — uma foto dos silos. São aceites ficheiros PNG e JPG.
4. Clique em **Seguinte** para passar para o **Fonte de dados** .
5. Por baixo da camada, clique em **Adicionar fonte de dados** — isto cria um bloco de fonte de dados vazio. No bloco, clique em **Escolher dispositivo** e selecione o sensor de nível do primeiro silo.
6. Clique em **Adicionar métrica**. Defina **Tipo de dados** para **Telemetria**, escolha a leitura do nível de enchimento em **Métrica do dispositivo**, e escolha um **Ícone**.
> **Não consegue encontrar a sua métrica?** O widget de imagem só fixa métricas numéricas. Se uma leitura que espera estiver em falta, a métrica está guardada como String ou Boolean em vez de Integer ou Float. Abra **Dispositivos → Métricas**, encontre a métrica e altere a forma como está guardada para Integer ou Float — desde que o dispositivo realmente reporte um número. Consulte [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md).
7. Clique em **Condições: N** para abrir a janela modal Condições. Defina uma **Cor predefinida**, e depois, para cada intervalo, clique em **Adicionar condição** e preencha a linha — uma **Nome da condição**, **Tipo de dados** definida para **Número**, a **De** e **Até** valores, e uma **Cor**. A cor do pin vem inteiramente destas condições. Para um nível de enchimento de silo reportado em percentagem, adicione quatro:
* "Crítico" — **De** 0, **Até** 10 — bordô (um vermelho escuro)
* «Reabastecer agora» — **De** 10, **Até** 30 — vermelho
* «Reabastecer em breve» — **De** 30, **Até** 60 — amarelo
* «Saudável» — **De** 60, **Até** 100 — verde
Clique em **Guardar** para fechar o modal. O pin passa agora a mostrar verde enquanto o silo está bem abastecido e desce através de amarelo e vermelho até uma pequena faixa bordô à medida que esvazia — assim, um olhar para a foto diz ao operador qual tanque precisa de ser abastecido.
8. O pin desse sensor aparece na imagem. **Arraste-o** para o silo a que pertence. Use os controlos de zoom (+ / −) na pré-visualização para o colocar com precisão.
9. Repita — **Adicionar fonte de dados** para o sensor de cada um dos silos restantes, adicione a respetiva métrica e condições, e arraste o respetivo pin para o tanque certo. Uma camada pode conter várias fontes de dados, e uma fonte de dados várias métricas.
10. Clique em **Guardar** para adicionar o widget ao painel.
O resultado: a foto do local com um pin colorido em cada silo, cada um mostrando a respetiva percentagem de enchimento em tempo real — todo o pátio de armazenamento legível à primeira vista. Os mesmos passos servem para qualquer imagem; só mudam a imagem, os dispositivos e as bandas de condições.
## O que são camadas
A **camada** é uma vista de imagem dentro do mesmo widget de imagem — não uma sobreposição transparente numa única imagem. Cada camada tem a sua própria imagem carregada e os seus próprios pinos. Quando o widget tem mais do que uma camada, um **alternador de camadas** aparece nele; o utilizador clica nele para alternar entre as vistas, pelo que várias imagens e conjuntos de sensores ficam num único widget.
As camadas fazem todo o sentido quando uma imagem não consegue mostrar tudo. Veja os silos — um único silo pode ter muito mais do que um sensor:
* **Camada 1 — "Pátio dos silos".** A foto exterior de todos os silos, com um pin de nível de enchimento em cada um. Esta vista responde a *qual silo precisa de atenção*.
* **Camada 2 — "Dentro do Silo 1".** Quando um silo tem uma série de sensores — por exemplo, um cabo de temperatura com vários pontos que desce pelo interior — carregue uma imagem aberta, em corte, desse silo e fixe nela cada sensor interno. Esta vista responde a *o que está a acontecer dentro desse silo*.
No dashboard, o operador clica no alternador de camadas para passar da visão geral do pátio diretamente para o detalhe interior, sem sair do widget nem abrir uma lista de dispositivos. Outras camadas seguem o mesmo padrão — uma foto da área do tapete rolante e da bomba, um diagrama do painel de controlo — cada uma com a sua própria imagem e os seus próprios pinos.
As camadas também se adaptam perfeitamente a um edifício de vários pisos. Dê a cada piso a sua própria camada — o rés do chão na Camada 1, os pisos acima nas respetivas camadas — e fixe temperatura, humidade ou ocupação nos pontos de AVAC de cada um. A equipa de instalações usa o alternador de camadas para percorrer o edifício piso a piso a partir de um único widget, com cada piso ajustado à sua própria especificação.
Uma planta aqui é simplesmente uma imagem plana: os desenhos de arquitetura já existentes são apenas carregados, um por piso — não é preciso desenhar ou modelar nada. Os dois são ferramentas diferentes: o widget de imagem fixa leituras em tempo real em plantas 2D planas que já tem, enquanto o [Digital Building Twin](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/digital-building-twin.md) serve para desenhar e operar um modelo 3D completo das instalações a partir do zero.
**Camadas ou widgets separados?** Use camadas quando as imagens forem vistas diferentes do mesmo local ou sistema. Use widgets de imagem separados quando as imagens pertencem a partes diferentes do dashboard ou abrangem sistemas não relacionados.
Para trabalhar com camadas: **Camada 1** já lá está — renomeie-a e carregue a respetiva imagem. Clique em **Adicionar nova camada** apenas quando quiser outra vista de imagem no mesmo widget. **Cada camada precisa da sua própria imagem** — se adicionar uma camada e a deixar vazia, **Seguinte** não continuará. No **Fonte de dados** separador, adicione cada fonte de dados e métrica por baixo da camada a que pertence e arraste cada pin na imagem dessa camada.
## Exemplos práticos
**Pátio dos silos de grãos — níveis de enchimento à primeira vista** Uma foto do local dos silos com um pin de nível de enchimento em cada tanque; condições verdes acima de 60%, amarelo de 30–60%, vermelho de 10–30%, bordô abaixo de 10%. Uma segunda camada contém um corte do silo mais movimentado com os sensores de temperatura internos fixados ao longo do cabo.
**Esquema do equipamento — leituras na máquina** Um esquema de uma linha de produção, uma leitura de vibração fixada em cada motor e rolamento — verde 0–7 mm/s, âmbar 7–12, vermelho acima de 12. O engenheiro vê qual componente está a funcionar mal sem associar nomes de dispositivos às máquinas.
**Edifício de vários pisos — uma camada por piso** A planta de cada piso na sua própria camada, com o AVAC e a temperatura fixados por piso — um piso de servidores com uma banda mais restrita do que os escritórios.
A imagem pode ser qualquer coisa que possa fotografar ou desenhar — um parque de tanques, uma sala de quadros, uma câmara frigorífica, um mapa do local — por isso trate estes exemplos como pontos de partida, não como limites. Sempre que uma leitura faça mais sentido quando vê *onde* ela está, o widget de imagem coloca-a lá.
## O que o widget mostra
No dashboard, cada camada mostra a respetiva imagem com um pin circular colorido em cada posição que definiu. Cada pin traz o ícone do sensor, o seu valor atual em tempo real e a unidade, e atualiza em tempo real à medida que o sensor reporta.
**A cor do pin vem inteiramente das condições.** A primeira condição correspondente vence; se nenhuma condição corresponder, o pin usa a cor Predefinida definida no modal de Condições. O widget de imagem visualiza o estado — para ser alertado quando uma leitura cruza um limite, combine-o com um [Alarme](/kilo-docs-pt/kilo-iot-server/alarm.md).
Quando um widget tem duas ou mais camadas, o **alternador de camadas** permite ao utilizador mover-se entre elas. Se uma camada ainda não tiver imagem, ou se o widget não tiver sensores configurados, essa área mostra em vez disso uma breve mensagem de espaço reservado.
## Ver também
* [Condições](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/conditions.md) — As regras de cor que determinam a cor de cada pin
* [Adicionar widgets](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets.md) — Modo de edição e o seletor de widgets
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/image-widget.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
