> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/user/canvas.md).

# 캔버스

## 목차

* [개요](#overview)
* [화면 구성 — 3개 화면](#layout)
* [목록 화면 (`/canvas/index`)](#list)
* [편집 화면 (`/canvas/edit`)](#edit)
  * [좌측 — 기본 정보 탭](#edit-info)
  * [좌측 — 편집 탭 (SVG 업로드 + 위젯 팔레트 11종)](#edit-widgets)
  * [우측 — 캔버스 미리보기](#edit-preview)
* [위젯 11종 자세히](#widgets)
  * [태그값 (tag\_value)](#widget-tag-value)
  * [시리즈 (timeseries)](#widget-timeseries)
  * [상태 (asset\_health)](#widget-asset-health)
  * [문서 (document)](#widget-document)
  * [타임라인 (asset\_timeline)](#widget-asset-timeline)
  * [게이지 (gauge)](#widget-gauge)
  * [KPI](#widget-kpi)
  * [메모 (memo)](#widget-memo)
  * [ISO (OEE/RAM/EMS)](#widget-iso)
  * [데이터 테이블 (data\_table)](#widget-data-table)
  * [이미지 (image)](#widget-image)
* [표시(view) / 전체화면(screen) 모드](#view-mode)
* [활용 시나리오](#use-cases)
* [자주 묻는 질문](#faq)
* [관련 화면](#related)

***

## 개요 <a href="#overview" id="overview"></a>

캔버스 메뉴는 SVG 도면 위에 실시간 위젯(태그값·차트·게이지·KPI·메모 등)을 배치해 운영 모니터링용 대시보드(스카다 형태)를 만드는 화면입니다. 운영자가 그래픽 편집 기술 없이도 평면도/배관도/공정도 위에 클릭만으로 데이터 표시 위젯을 배치할 수 있습니다.

| 화면       | 내부 URL                       | 용도                           |
| -------- | ---------------------------- | ---------------------------- |
| **목록**   | `/canvas/index`              | 내가 만든 캔버스 + 공유받은 캔버스 카드 그리드  |
| **편집**   | `/canvas/edit/{canvas_id}`   | SVG 업로드 + 위젯 11종 배치 + 공유 설정  |
| **표시**   | `/canvas/view/{canvas_id}`   | 캔버스를 일반 모드로 조회 (헤더·메뉴 함께)    |
| **전체화면** | `/canvas/screen/{canvas_id}` | 캔버스만 전체화면 표시 (현장 모니터·디스플레이용) |

**경로**: 왼쪽 메뉴 > **Visualization > 캔버스** (내부 URL `/canvas/index`)

***

## 화면 구성 — 3개 화면 <a href="#layout" id="layout"></a>

```
[목록]  →  [편집]  →  [표시 / 전체화면]
```

| 화면      | 주된 사용자                  |
| ------- | ----------------------- |
| 목록      | 모든 사용자                  |
| 편집      | 캔버스 소유자 / 공유 보안 그룹의 사용자 |
| 표시·전체화면 | 모든 인증 사용자 (공유된 경우)      |

***

## 목록 화면 (`/canvas/index`) <a href="#list" id="list"></a>

```
🎨 캔버스  [총 N 개]                            [➕ 새 캔버스] [↻]
```

### 상단 도구

| 컨트롤       | 동작                                         |
| --------- | ------------------------------------------ |
| **새 캔버스** | 빨강 + ➕ — `addCanvas()` — 새 캔버스 생성 폼 열기     |
| **새로고침**  | 빨강 + ↻                                     |
| **총 N 개** | 내 캔버스 + 공유받은 캔버스 합계 (`canvas_total_count`) |

### 좌측 사이드바 (col-lg-2) — 필터링

| 컨트롤                         | 폭     | 설명                   |
| --------------------------- | ----- | -------------------- |
| **사이트 셀렉터** (`filter_site`) | 100%  | 전체 사이트 + 등록된 사이트     |
| **캔버스 명** (`search_name`)   | 100%  | placeholder: "캔버스 명" |
| **설명** (`search_desc`)      | 100%  | placeholder: "설명"    |
| **검색** (`filterList()`)     | 100px | 위 조건으로 카드 목록 갱신      |

### 우측 (col-lg-10) — 카드 그리드

```
┌─ 캔버스 목록 [N] · 검색된 캔버스 ───────────────────┐
│                                                  │
│  ┌─카드─┐ ┌─카드─┐ ┌─카드─┐ …                   │ ← canvas_list_view
│  │ 260px│ │ 260px│ │ 260px│                       │   (eq-card 260px 그리드)
│  └─────┘ └─────┘ └─────┘                          │
└──────────────────────────────────────────────────┘
```

각 카드는 **260px 폭**의 균일한 크기로 격자에 자동 정렬되며, 카드 전체 영역이 클릭 가능합니다(설정의 별도 "표시" 버튼 없이 카드를 클릭하면 캔버스 표시 화면으로 이동).

| 항목          | 설명                                         |
| ----------- | ------------------------------------------ |
| **제목**      | 캔버스 명                                      |
| **설명**      | 캔버스 설명                                     |
| **사이트**     | 소속 사이트                                     |
| **소유자**     | 등록 사용자 ID                                  |
| **수정일**     | 마지막 수정 시각                                  |
| **타입**      | `my` (내가 만듬) / `shared` (공유받음) — 색상 뱃지로 구분 |
| **카드 클릭**   | 표시 화면(`/canvas/view`)으로 이동                 |
| **편집 / 삭제** | 카드 우측 액션 버튼 — 카드 클릭과 별개로 동작 (이벤트 버블링 중단)   |

> 캔버스 카드는 두 그룹(내 캔버스 `_myList` + 공유받은 캔버스 `_shareList`)을 통합해 표시합니다. 사이트·이름·설명 필터로 좁힐 수 있으며, 검색 결과가 0건이면 안내 빈 상태 화면(SVG 일러스트 + 메시지)이 표시됩니다.

***

## 편집 화면 (`/canvas/edit`) <a href="#edit" id="edit"></a>

화면은 좌측 col-lg-3 속성 패널 + 우측 col-lg-9 캔버스 미리보기로 구성됩니다. 좌측에는 두 개 상위 탭(**기본 정보** / **편집**)이 있습니다.

### 좌측 — 기본 정보 탭 <a href="#edit-info" id="edit-info"></a>

#### 기본 정보 패널

| 입력          | path           | 설명                              |
| ----------- | -------------- | ------------------------------- |
| **캔버스 ID**  | `canvas_id`    | 수정 모드(`mode='U'`)에서만 표시 (읽기 전용) |
| **사이트 선택**  | `site_id`      | 사이트명 \[설명] 옵션                   |
| **캔버스 명** ⭐ | `canvas_title` | 필수 입력                           |
| **설명**      | `canvas_desc`  | 자유 텍스트                          |

#### 공유 설정 패널

| 입력           | path                | 설명                                                                           |
| ------------ | ------------------- | ---------------------------------------------------------------------------- |
| **공유 사용**    | `share` (체크박스)      | "이 캔버스를 보안 그룹의 사용자와 공유합니다."                                                  |
| **공유 보안 그룹** | `share_security_id` | [보안 정책](/plantpulse-platform/user/security.md#security-policy) 에 등록된 그룹에서 선택 |

### 좌측 — 편집 탭 <a href="#edit-widgets" id="edit-widgets"></a>

캔버스에 표시할 SVG 도면 업로드 + 위젯 팔레트 11 종.

#### SVG 도면 패널

| 컨트롤                         | 동작                               |
| --------------------------- | -------------------------------- |
| **파일 선택** (`svg_file_name`) | 클릭 또는 폴더 아이콘 — `.svg` 파일 선택      |
| **SVG 업로드**                 | `upload_btn` — 선택한 SVG 를 캔버스에 적용 |

> SVG 는 평면도·배관도·공정도 등 운영자가 보고 싶은 도면입니다. SVG 가 없으면 캔버스 영역에 "SVG 도면을 업로드하세요." 안내가 표시됩니다.

#### 위젯 팔레트 11 종

상단 탭 헤더에서 위젯 종류를 선택하고, 각 탭의 입력을 채운 뒤 **배치** 버튼을 클릭하면 캔버스 위에 클릭으로 위치를 지정할 수 있습니다(클릭 모드 안내가 캔버스 상단에 노란 배경으로 표시됨).

| 탭  | 아이콘 | data-tab         | 위젯                |
| -- | --- | ---------------- | ----------------- |
| 1  | 🏷  | `tag_value`      | 태그값               |
| 2  | 📈  | `timeseries`     | 시리즈               |
| 3  | ❤️  | `asset_health`   | 상태                |
| 4  | 📄  | `document`       | 문서                |
| 5  | 📊  | `asset_timeline` | 타임라인              |
| 6  | 🌡️ | `gauge`          | 게이지               |
| 7  | 🚦  | `kpi`            | KPI               |
| 8  | 📌  | `memo`           | 메모                |
| 9  | 🎖  | `iso`            | ISO (OEE/RAM/EMS) |
| 10 | 📋  | `data_table`     | 데이터 테이블           |
| 11 | 🖼  | `image`          | 이미지               |

#### 배치된 위젯 목록

위젯 팔레트 하단에 배치된 위젯 목록이 표시됩니다(`placed_widgets_list`, 최대 330px 스크롤). 헤더에 위젯 수(`widget_count`)가 함께 표시됩니다.

빈 상태 (위젯 0개일 때):

```
       ▦ (그리드 아이콘)
   배치된 위젯이 없습니다
상단 팔레트에서 위젯을 끌어서 캔버스에 배치하세요.
```

#### 폼 제출 (좌측 하단)

| 버튼          | 동작                                             |
| ----------- | ---------------------------------------------- |
| **목록** (☰)  | `goIndex()` — 캔버스 목록으로                         |
| **저장** (파랑) | `save()` — 캔버스 + 위젯 + tag\_mapping\_json 전체 저장 |

### 우측 — 캔버스 미리보기 <a href="#edit-preview" id="edit-preview"></a>

| 영역                                      | 설명                                                     |
| --------------------------------------- | ------------------------------------------------------ |
| **헤더**                                  | 🖥 "캔버스 미리보기"                                          |
| **배치 모드 안내** (`placing_mode_indicator`) | 클릭으로 위젯 위치를 지정 중일 때 노란 배경의 안내 — "클릭하여 태그를 배치하세요"·취소 링크 |
| **본문** (750px 높이, overflow: auto)       | SVG 도면 위에 위젯 마커가 표시되는 영역                               |

#### SVG 컨테이너 (`svg_container`)

* SVG 가 업로드되어 있으면 `<svg>` 로 렌더링
* 비어 있으면 빈 상태 안내 표시:

```
       🖼 (칠판 아이콘)
    SVG 도면이 없습니다
좌측 [설정] 탭에서 SVG 도면을 업로드하세요.
```

#### 마커 레이어 (`marker_layer`)

배치한 위젯 위치에 마커가 떠 있으며, 마커 클릭 시 위젯 편집(이동·삭제·옵션 변경)이 가능합니다. 위젯 간 연결선은 별도 라이브러리(leader-line)로 시각화됩니다.

***

## 위젯 11종 자세히 <a href="#widgets" id="widgets"></a>

각 위젯의 입력 필드와 동작을 정리합니다. 모든 위젯은 우측 캔버스에 마커로 배치되며, 표시 모드(`/canvas/view`)에서 실시간 데이터로 갱신됩니다.

### 태그값 (tag\_value) <a href="#widget-tag-value" id="widget-tag-value"></a>

가장 단순한 위젯. 한 태그의 현재 값을 도면 위에 큰 숫자로 표시합니다.

| 입력        | id              | 형태   |
| --------- | --------------- | ---- |
| **태그 ID** | `new_tag_input` | 자동완성 |

### 시리즈 (timeseries) <a href="#widget-timeseries" id="widget-timeseries"></a>

| 입력        | id             | 형태                     |
| --------- | -------------- | ---------------------- |
| **태그 ID** | `ts_tag_input` | 자동완성                   |
| **기간**    | `ts_period`    | 최근 1시간/6시간/12시간/1일(기본) |

작은 시계열 차트가 도면 위에 표시되어 변화 추세를 한눈에 볼 수 있습니다.

### 상태 (asset\_health) <a href="#widget-asset-health" id="widget-asset-health"></a>

자산의 건강 상태를 색상 점등으로 표시합니다.

| 입력        | id               | 형태           |
| --------- | ---------------- | ------------ |
| **에셋 ID** | `ah_asset_input` | 자동완성 (자산 트리) |

색상은 [상태 코드](/plantpulse-platform/user/status.md#health-status) 의 4단계(NORMAL/WARN/ERROR/UNKNOWN).

### 문서 (document) <a href="#widget-document" id="widget-document"></a>

자산에 등록된 도면·매뉴얼·QR 코드 등 문서를 도면 위에 표시합니다.

| 입력        | id                | 형태   |
| --------- | ----------------- | ---- |
| **에셋 ID** | `doc_asset_input` | 자동완성 |

### 타임라인 (asset\_timeline) <a href="#widget-asset-timeline" id="widget-asset-timeline"></a>

자산의 가동/정지·이벤트 타임라인을 도면 위에 작게 표시합니다.

| 입력        | id               | 형태                   |
| --------- | ---------------- | -------------------- |
| **에셋 ID** | `tl_asset_input` | 자동완성                 |
| **표시 범위** | `tl_range`       | 최근 1·3·6·12·24시간(기본) |

### 게이지 (gauge) <a href="#widget-gauge" id="widget-gauge"></a>

태그 값의 현재 위치를 게이지로 시각화합니다.

| 입력         | id                | 형태   | 기본값 |
| ---------- | ----------------- | ---- | --- |
| **태그 ID**  | `gauge_tag_input` | 자동완성 | —   |
| **최솟값**    | `gauge_min`       | 숫자   | 0   |
| **최댓값**    | `gauge_max`       | 숫자   | 100 |
| **경고 임계값** | `gauge_warn`      | 숫자   | 70  |
| **위험 임계값** | `gauge_error`     | 숫자   | 90  |

### KPI <a href="#widget-kpi" id="widget-kpi"></a>

핵심 지표를 색상 등급(녹색/노랑/빨강)으로 표시합니다.

| 입력        | id               | 형태   | 기본값 |
| --------- | ---------------- | ---- | --- |
| **태그 ID** | `kpi_tag_input`  | 자동완성 | —   |
| **라벨**    | `kpi_label`      | 텍스트  | —   |
| **정상 최대** | `kpi_normal_max` | 숫자   | 50  |
| **경고 최대** | `kpi_warn_max`   | 숫자   | 80  |

값이 정상 최대 이하면 녹색, 경고 최대까지 노랑, 그 이상은 빨강.

### 메모 (memo) <a href="#widget-memo" id="widget-memo"></a>

운영자 안내문·라벨·주석을 도면 위에 직접 작성합니다.

| 입력        | id               | 형태            | 기본값       |
| --------- | ---------------- | ------------- | --------- |
| **텍스트**   | `memo_text`      | textarea (3행) | —         |
| **글꼴 크기** | `memo_font_size` | 숫자 (8\~48)    | 14        |
| **색상**    | `memo_color`     | 색상 선택기        | `#333333` |

### ISO (OEE/RAM/EMS) <a href="#widget-iso" id="widget-iso"></a>

ISO 데이터 및 분석 차트를 도면에 임베드합니다.

| 입력        | id                | 형태                 |
| --------- | ----------------- | ------------------ |
| **하위 탭**  | `iso-sub-tabs`    | OEE / RAM / EMS 토글 |
| **에셋 ID** | `iso_asset_input` | 자동완성               |

선택한 하위 탭(`oee_chart`/`ram_chart`/`ems_chart`)에 따라 그 자산의 해당 분석 차트가 도면 위에 표시됩니다. 자세한 지표 정의는 [ISO 데이터 및 분석](/plantpulse-platform/user/plugins.md) 참고.

### 데이터 테이블 (data\_table) <a href="#widget-data-table" id="widget-data-table"></a>

자산의 핵심 태그 여러 개를 표 형태로 도면 위에 배치합니다.

| 입력        | id                | 형태       |
| --------- | ----------------- | -------- |
| **에셋 ID** | `tbl_asset_input` | 자동완성     |
| **라벨**    | `tbl_label`       | 텍스트 (선택) |

### 이미지 (image) <a href="#widget-image" id="widget-image"></a>

외부 URL 의 이미지(예: CCTV 스냅샷·웹캠)를 도면 위에 표시합니다.

| 입력             | id            | 형태       | 기본값                        |
| -------------- | ------------- | -------- | -------------------------- |
| **이미지 URL**    | `img_url`     | 텍스트      | placeholder: `https://...` |
| **라벨**         | `img_label`   | 텍스트 (선택) | —                          |
| **새로고침 간격(초)** | `img_refresh` | 숫자       | 0 (없음)                     |

`0` 이면 한 번만 로드, 값이 있으면 그 초 간격으로 자동 새로고침.

***

## 표시(view) / 전체화면(screen) 모드 <a href="#view-mode" id="view-mode"></a>

| 모드       | 내부 URL                       | 표시                          |
| -------- | ---------------------------- | --------------------------- |
| **표시**   | `/canvas/view/{canvas_id}`   | 캔버스 + 좌측 메뉴 + 상단 헤더 (일반 보기) |
| **전체화면** | `/canvas/screen/{canvas_id}` | 캔버스만 화면 가득 (메뉴·헤더 없음)       |

### 표시 모드 (view\.jsp)

캔버스 카드의 ▶ 표시 버튼으로 진입합니다. SVG 도면 위에 모든 위젯이 실시간 데이터로 갱신되어 표시되며, 우상단의 ⛶ 전체화면 버튼으로 전체화면 모드로 전환할 수 있습니다.

### 전체화면 모드 (screen.jsp)

현장 모니터·대형 디스플레이·파견 안내판 등에 띄울 때 사용합니다. 메뉴·헤더가 없어 캔버스 자체만 화면을 가득 채웁니다.

> 표시 모드는 위젯이 자동으로 실시간 데이터로 갱신됩니다. 데이터가 인입되지 않으면 위젯이 비어 있거나 회색으로 표시됩니다.

***

## 활용 시나리오 <a href="#use-cases" id="use-cases"></a>

| 시나리오                    | 절차                                              |
| ----------------------- | ----------------------------------------------- |
| **공정도 위에 실시간 온도/압력 표시** | SVG 공정도 업로드 → 태그값 위젯 N개 배치 (태그 ID 자동완성)         |
| **라인 가동 상태 한눈에**        | 라인 평면도 SVG → 자산 상태(asset\_health) 위젯을 설비별로 배치   |
| **현장 디스플레이용 대시보드**      | 캔버스 만들기 → 화면 가득 위젯 배치 → 현장 PC 에서 전체화면 모드로 띄우기   |
| **CCTV + 운영 데이터 통합 화면** | 이미지 위젯(CCTV URL, 5초 새로고침) + 핵심 KPI 위젯 함께 배치     |
| **OEE 모니터링 보드**         | 라인 SVG → ISO 위젯(OEE) + 자산 상태 위젯 + 게이지 위젯 조합     |
| **품질 검사 현황**            | 검사 라인 SVG → 데이터 테이블 위젯 + 메모 위젯 + KPI 위젯         |
| **팀별 공유 대시보드**          | 캔버스 편집 → 공유 사용 ON + 보안 그룹 선택 → 그 그룹 사용자에게 자동 공유 |

***

## 자주 묻는 질문 <a href="#faq" id="faq"></a>

**Q. SVG 가 없어도 캔버스를 만들 수 있나요?** A. 만들 수는 있지만 위젯을 배치할 좌표가 없어 의미가 없습니다. 평면도·배관도·공정도 SVG 를 먼저 업로드하시기를 권장합니다.

**Q. SVG 파일을 어디서 구하나요?** A. 각 사이트의 도면 담당자에게 요청하시거나, 일반 도면(PDF·이미지)을 외부 도구로 SVG 변환하여 사용할 수 있습니다.

**Q. 위젯을 잘못 배치했어요.** A. 캔버스 위 마커를 클릭하면 옵션 메뉴가 열려 이동·삭제·편집할 수 있습니다.

**Q. 동일 태그를 여러 위치에 표시해도 되나요?** A. 네, 같은 태그를 여러 위젯에서 표시할 수 있습니다. 예를 들어 한 자산의 온도를 게이지·시리즈·KPI 위젯 3 종으로 동시에 표시.

**Q. 캔버스를 다른 사용자와 공유하려면?** A. 편집 화면의 **공유 설정** 패널에서 **이 캔버스를 보안 그룹의 사용자와 공유합니다** 를 체크하고 보안 그룹을 선택하세요. 그 그룹의 사용자는 자신의 캔버스 목록의 "공유받은" 영역에서 확인할 수 있습니다.

**Q. 표시 모드에서 위젯이 회색으로 표시됩니다.** A. 그 위젯이 가리키는 태그·자산의 데이터가 아직 인입되지 않은 경우입니다. [대시보드](/plantpulse-platform/user/summary.md) 화면이나 [연결 관리](/plantpulse-platform/user/connection.md) 에서 데이터 인입을 확인하세요.

**Q. 전체화면 모드로 띄웠는데 일정 시간 후 화면이 잠깁니다.** A. 브라우저 또는 OS 의 화면 보호기/세션 만료 때문입니다. 현장 디스플레이라면 브라우저의 자동 화면 보호기를 끄고, 시스템 설정에서 OS 화면 보호기도 비활성화하세요.

**Q. 게이지의 임계값을 자동으로 갱신하고 싶어요.** A. [플로우](/plantpulse-platform/user/flow.md) 의 `flow_update_tag_alarm_band_numeric` 노드를 사용해 자동화할 수 있습니다.

**Q. 데이터 테이블 위젯에 어떤 컬럼이 표시되나요?** A. 그 자산에 등록된 핵심 태그 들이 자동으로 표시됩니다. 자산별 핵심 태그 매핑은 [팩토리 관리](/plantpulse-platform/user/factory.md) 의 자산 트리에서 설정할 수 있습니다.

**Q. 이미지 위젯의 새로고침 간격을 너무 짧게 잡으면?** A. 외부 이미지 서버에 부하가 갈 수 있고 네트워크 사용량이 늘어납니다. 5초 이상으로 잡으시기를 권장합니다.

**Q. 캔버스를 백업하거나 다른 환경으로 이동하고 싶어요.** A. 화면에서 직접 export 는 제공되지 않습니다. SVG 자체는 따로 보관하시고, 캔버스 정의(위젯 매핑)를 옮기려면 시스템 관리자에게 문의하세요.

***

## 관련 화면 <a href="#related" id="related"></a>

* [팩토리 관리](/plantpulse-platform/user/factory.md) — 자산·태그 등록 (위젯이 가리키는 대상)
* [데이터 포인트](/plantpulse-platform/user/data-point.md) — 위젯이 표시하는 태그 데이터의 트렌드 화면
* [ISO 데이터 및 분석](/plantpulse-platform/user/plugins.md) — ISO 위젯의 OEE/RAM/EMS 차트 원본 화면
* [설비](/plantpulse-platform/user/equipment.md) — 자산 카드와의 연계
* [보안 관리](/plantpulse-platform/user/security.md) — 공유 보안 그룹 설정
* [상태 코드 정의](/plantpulse-platform/user/status.md#health-status) — 상태 위젯의 색상 매핑