옮길 수 있는 SVG 심볼

안전한 Ganter 바인딩과 형식 있는 연결점을 갖춘 정적 SVG 심볼을 만들고 나누어 씁니다.

Ganter 심볼은 그림과 실시간 데이터를 따로 둡니다. 그림은 평범한 정적 SVG이고, 값 대응과 움직임은 모두 Ganter Lab이 가집니다. 그래서 가져온 파일은 스크립트도, 이벤트 처리기도, 안에 심어 둔 애니메이션 코드도, 네트워크 요청도 돌릴 수 없습니다. 이 페이지는 그것을 만드는 모델에 대한 완전한 참고 자료입니다. 심볼이 무엇을 선언하는지, 가져오기가 무엇을 받아들이고 무엇을 거부하는지, 그리고 심볼이 스테이션 사이를 어떻게 옮겨 다니는지입니다.

심볼은 자기 그림 위에 세 가지를 선언합니다.

• 가변 영역: 이름이 붙은 입력(채움, 선, 움직임, 글자, 보임)이며, 나중에 놓인 대시보드 인스턴스가 Logic 주소나 고정된 값으로 그것을 먹입니다.
• 연결점: 테두리에 놓인 형식 있는 연결 지점이며, 대시보드가 심볼 사이로 배관과 덕트와 배선과 축을 이어 갈 수 있게 합니다.
• 제안: 선택 사항이며, 다른 심볼과 어떻게 놓이는지를 자세로까지 밝힌 조합입니다.

시스템 심볼과 내 심볼

카탈로그의 출처는 둘이며, 심볼이 나열되는 모든 곳에서 걸러 볼 수 있습니다.

모든 시스템 심볼은 내 심볼로 복제를 내놓습니다. 복사본은 얼어붙은, 독립적으로 소유되는 사용자 자산이며(그림, 뷰 박스, 맞춤, 크기, 가변 영역, 종류 구성, 연결점, 제안이 함께 복사됩니다), 나중에 앱을 갱신하면서 원본이 바뀌어도 고른 그대로 동작합니다. 사용자 심볼을 지울 때는 확인을 묻고, 그것을 아직 참조하는 대시보드는 깨지는 대신 자리 표시를 보여 줍니다.

심볼을 만드는 방법

• 파일 가져오기: Logic > 자산 > 심볼 > 심볼 가져오기는 평범한 .svg나 완전한 .ganter-symbol.json 패키지를 받습니다. 모든 가져오기는 자기 신원을 가진 새 자산을 만듭니다. 있던 심볼을 결코 덮어쓰지 않으며, 이름이 부딪히면 실패하는 대신 꼬리를 붙여 풉니다(" 2", " 3", …). 선택기는 1 MB가 넘는 파일을 바이트를 읽기 전에 거부합니다. 평범한 SVG를 가져온 뒤에는 안전하지 않은 항목을 몇 개나 없앴는지 앱이 알려 줍니다.
• 앱 안에서 만들기: 새 사용자 심볼은 이름, SVG 마크업, 대시보드 배치(맞춤과 처음 크기), 그리고 가변 영역을 위한 편집기를 엽니다. 심볼이 생긴 뒤에는 올바른 변경이 저절로 저장됩니다. 연결점의 좌표는 앱에서 일부러 편집할 수 없습니다. 형식 있는 연결점은 패키지로만 넣을 수 있고, 패키지가 정한 연결점은 나중에 편집해도 읽기 전용으로 그대로 남습니다.
• AI에게 부탁하기: 두 길이 똑같은 규약을 함께 씁니다. 내장 MCP 엔드포인트에서는 symbol_validate 도구가 가져오기를 시험 삼아 돌려 보고 symbol_import가 새 자산을 저장합니다. 둘 다 그 설명에 규약 전체를 담고 있습니다. 앱에 닿을 수 없는 바깥 대화에서는 심볼 패널의 대화 지시문 복사가 자족적인 지시문을 복사합니다. 돌아온 SVG나 패키지를 파일로 저장해 여기에서 가져오십시오.

둘레의 자산 작업 영역은 Logic을 보십시오.

평범한 SVG 준비하기

묶고 싶은 부분마다 변하지 않는 SVG id를 주십시오. 가져온 뒤에는 그 id가 가변 영역의 대상 선택기에 나타납니다. id와 가변 영역 이름은 하나의 문법을 함께 씁니다. 글자나 _로 시작해 글자와 숫자와 _와 .와 :와 -로 이어지며 최대 128자입니다.

선택 사항인 data-ganter-* 속성은 심볼이 담을 수 있는 유일한 Ganter 전용 마크업입니다.

연결점은 SVG 안에 살지 않으며 SVG 요소 id를 겨냥하지도 않습니다. data-ganter-port나 data-ganter-port-*라는 이름의 속성은 이 형식의 일부가 아닙니다. 평범한 SVG 가져오기는 그것을 걷어 내고, 그것을 담은 엄격한 패키지는 거부됩니다.

평범한 SVG 가져오기는 언제나 올바른 보기 전용 심볼을 내놓습니다. 연결점 0개, 가변 영역 0개입니다. 검사기는 역할과 종류와 바깥 방향과 내부 경로가 선언되지 않았기 때문에 이을 수 있는 연결점이 없다고 알립니다. Ganter는 파일 이름이나 범주나 그림에서 그 값을 추측하지 않으며, 내부 연결점 편집기나 경로 편집기를 열지도 않습니다.

정화기가 받아들이는 것

같은 SVG 정책이 모든 길(파일 가져오기, 앱 안 편집기, MCP, 패키지)에 적용됩니다. 이 정책은 일부러 SVG보다 좁습니다.

• 남기는 것: 동작이 없는 기하와 구조입니다. svg, g, defs, symbol, use, path, rect, circle, ellipse, line, polyline, polygon, text, tspan, title, desc, clipPath, mask, linearGradient, radialGradient, stop, pattern, marker이며 표시 속성(채움, 선, 불투명도, 변환, 스타일)과 ARIA 이름표가 함께 남습니다.
• 걷어 내거나 거부하는 것: <script>, <style>, <foreignObject>, 이벤트 처리기, 안에 심어 둔 애니메이션, 그리고 모든 외부 URL과 data:/file:/http(s) URL입니다. 내부 url(#id)와 href="#id" 참조만 살아남습니다.
• 한계: 마크업은 최대 512 KB, 요소 4096개까지입니다.

안전한 칠하기는 16진수 색, CSS 이름 색, rgb()/rgba()/hsl()/hsla(), 그리고 앱의 테마 토큰 var(--color-<name>)(예를 들어 var(--color-success), var(--color-symbol-off))입니다. 테마 토큰은 하나의 그림이 밝은 테마와 어두운 테마에 함께 맞는 방법입니다. 테마 변형 둘을 만들지 말고 토큰을 참조하는 그림 하나를 실으십시오.

어긴 것을 어떻게 다루는지는 길에 따라 다릅니다. 평범한 SVG는 고칩니다(안전하지 않은 항목을 걷어 내고 걷어 낸 것마다 경고로 알립니다). 패키지는 엄격해서, 조용히 고쳐지는 대신 처음 어긴 것들을 밝히며 거부됩니다.

옮길 수 있는 패키지 v2

심볼을 내보내면 .ganter-symbol.json 파일이 만들어집니다. 봉투의 모든 칸이 필수입니다. 규약의 배열 셋은 비어 있어도 되지만 반드시 있어야 합니다.

공개된 Ganter symbol v2 JSON Schema가 전송 봉투를 검사합니다. 그다음 가져오기가 JSON Schema로는 표현할 수 없는 의미 검사를 합니다. SVG 대상이 있는지, 내부 경로의 기하가 맞는지, 제안이 어울리는지입니다. 패키지는 모든 면에서 엄격합니다. 안전하지 않은 마크업, 알 수 없는 칸, 배열 안의 null 항목, 그리고 예전의 ports[]와 anchors[]와 profile과 connectionStyle 규약은 고쳐지는 것이 아니라 거부됩니다.

패키지는 스테이션 주소도, 대시보드 바인딩도, 인스턴스마다의 종류 선택도, 데이터베이스 GUID도, 사용자 신원도 결코 담지 않습니다. Logic 주소를 담은 가변 영역은 내보낼 수조차 없습니다. 그 주소는 다시 쓰는 심볼이 아니라 놓인 인스턴스의 것이기 때문입니다.

크기와 뷰 박스와 맞춤

뷰 박스는 심볼의 자연스러운 좌표 공간입니다. 연결점과 내부 경로가 그 안에서 선언되며, SVG 뿌리 자신의 viewBox와 정확히 같아야 합니다. 두 뷰 박스가 어긋나는 패키지는 거부됩니다. 정사각형이 아닌 뷰 박스도 온전히 지원하므로, 긴 컨베이어가 정사각형 안에 살 필요는 없습니다.

맞춤 방식은 운전자가 그린 대시보드 사각형을 그림이 어떻게 쓰는지 말합니다.

크기는 심볼을 처음 놓을 때의 대시보드 격자 칸 수입니다. 너비 1에서 24, 높이 1에서 12입니다(편집기의 기본값은 4 × 4입니다). 이것은 제약이 아니라 제안이며, 운전자는 그 뒤에 자유롭게 크기를 바꿉니다.

가져오기의 크기는 서로 다른 두 관문이 가릅니다. 파일 선택기는 1 MB가 넘는 것을 읽기 전에 거부하고, 정화기는 512 KB나 요소 4096개를 넘는 마크업을 거부합니다.

가변 영역, 곧 바인딩 표면

가변 영역은 입력 하나를 선언합니다. 어느 요소를 움직이는지, 그것에 무엇을 하는지, 그리고 입력 값이 출력으로 어떻게 대응되는지입니다. 나중에 놓인 대시보드 인스턴스가 가변 영역마다 그 신호원(Logic 주소나 고정된 값)을 고릅니다. 심볼 자신은 결코 신호원을 저장하지 않습니다.

가변 영역마다 담는 것은 이렇습니다.

열세 가지 가변 영역 갈래는 이렇습니다.

이 가변 영역은 그림을 꾸밉니다. 대시보드 연결선 경로는 결코 꾸미지 않습니다. 그 색과 폭은 연결선 종류마다 공통입니다.

바인딩의 소유

심볼은 매개변수와 허락된 종류 선택을 선언하지, 실시간 신호원이나 인스턴스의 선택을 선언하지 않습니다. 심볼 구성 요소를 놓은 뒤에 운전자가 가변 영역마다 Logic 주소나 고정된 값을 대응시키고, 그 인스턴스에서 구성할 수 있는 연결선 종류를 고릅니다. 그 선택은 스테이션 안에 머물고 다시 쓰는 심볼과 함께 결코 내보내지지 않습니다. 대응되지 않은 가변 영역은 중립으로 남습니다. 요소는 원래 적힌 겉모습을 그대로 지킵니다.

공통 위치와 연결선 종류

모든 연결점은 고정된 열여섯 앵커 테두리 카탈로그에서 위치 하나를 참조합니다. 패키지는 anchorId만 저장하며 좌표를 되풀이하거나 덮어쓰지 않습니다. 뷰 박스에 대한 정규화된 비율로 적은 위치는 이렇습니다.

• 위: top-left (0, 0), top-25 (0.25, 0), top-50 (0.5, 0), top-75 (0.75, 0), top-right (1, 0)
• 오른쪽: right-25 (1, 0.25), right-50 (1, 0.5), right-75 (1, 0.75)
• 아래, 시계 방향으로: bottom-right (1, 1), bottom-75 (0.75, 1), bottom-50 (0.5, 1), bottom-25 (0.25, 1), bottom-left (0, 1)
• 왼쪽, 시계 방향을 이어서: left-75 (0, 0.75), left-50 (0, 0.5), left-25 (0, 0.25)

이것은 테두리 위의 위치이지 5×5 격자가 아닙니다. 심볼이 위치를 더하거나 자기 앵커 좌표를 저장할 수는 없습니다.

여덟 가지 공통 연결선 종류는 liquid, gas, air-duct, electrical, signal, network, material, mechanical-shaft입니다. 종류마다의 색과 표시 선 두께는 Logic > 자산 > 연결선 종류에서 설정하십시오. 심볼과 연결선은 변하지 않는 종류 id를 지니므로, 공통 값을 바꾸면 그것을 쓰는 모든 경로가 다시 칠해집니다. 패키지는 색이나 두께를 결코 복사하지 않으며 작음, 표준, 큼 같은 경로 변형도 두지 않습니다.

끝점 둘이 같은 종류로 풀릴 때 정의된 연결이 됩니다. 연결점의 역할은 만들고 검토하는 데 도움을 주지만, 그 자체로 어떤 연결망 배치를 금지하지는 않습니다.

함께 쓰는 종류 선택

여러 매체와 함께 일할 수 있는 심볼은 그림을 복제하는 대신 함께 쓰는 종류 구성을 선언합니다.

{
  "id": "process-type",
  "name": "Process type",
  "allowedTypes": ["liquid", "gas"],
  "defaultType": "liquid"
}

id는 변하지 않는 키입니다. 소문자와 숫자를 붙임표 하나로 이으며 처음과 끝은 글자나 숫자여야 합니다(대문자는 거부됩니다). allowedTypes는 비어 있지 않고 공통 종류 id를 겹치지 않게 담습니다. defaultType은 그 안에 있어야 하고 name은 필수입니다. process-type을 참조하는 모든 연결점은 놓인 대시보드 인스턴스에서 한 번 고른 선택을 따릅니다. 정의 하나가 공정 매체와 배기 매체처럼 서로 독립된 구성 여럿을 담을 수도 있고, 그동안 다른 연결점은 고정으로 남을 수 있습니다.

완전한 연결점

이을 수 있는 연결점은 저마다 공통 위치 하나, 역할 하나, 고정된 종류 하나 또는 함께 쓰는 구성 하나, 원래 방향에서의 바깥 방향, 그리고 안으로 들어오는 경로를 선언합니다.

{
  "anchorId": "left-50",
  "role": "input",
  "typeConfiguration": "process-type",
  "direction": "west",
  "internalPath": [
    { "x": 18, "y": 50 },
    { "x": 36, "y": 50 },
    { "x": 48, "y": 62 }
  ]
}

가져올 때 모두 지켜지는 규칙은 이렇습니다.

• 연결점은 최대 16개이고, 앵커 id는 저마다 많아야 한 번 쓰입니다.
• role은 input이나 output이나 bidirectional이고, direction은 north나 east나 south나 west입니다.
• type(공통 연결선 종류)과 typeConfiguration(선언된 구성 id) 가운데 정확히 하나여야 합니다. 둘 다도 안 되고 아무것도 없는 것도 안 됩니다.
• 공통 앵커를 SVG의 자연스러운 뷰 박스로 옮긴 자리가 internalPath의 암묵적인 시작점입니다. 그것을 첫 점으로 되풀이하지 마십시오. 좌표는 정규화된 비율이 아니라 뷰 박스의 절대값이고, 경로에는 적어도 점 하나가 있습니다.
• 모든 선분은 뷰 박스 안에 머물고 길이가 0이 아니며 수평이거나 수직이거나 정확히 45°입니다. 이어지는 선분은 많아야 90°까지 꺾입니다.
• 연결점을 두려면 SVG에 뷰 박스가 있어야 합니다.

대시보드는 내부 경로를 장비 그림 아래에 그리고, 크기 바꾸기와 90° 회전과 뒤집기에 맞추어 변환하며, 심볼과 함께 배율을 키우는 대신 공통 연결선 종류의 표시 폭을 지킵니다. 그래서 하나의 이어진 선이 한 본체 안쪽에서 다른 본체 안쪽까지 흐릅니다.

연결점은 전부이거나 전무입니다. 일부만 있는 연결점을 담은 엄격한 패키지는 올바르지 않습니다. 보기 전용 패키지는 대신 빈 terminals 배열을 씁니다. 빈자리를 채우려고 무엇을 추측하는 일은 결코 없습니다.

순서가 있는 제안

제안은 정확한 목표 자세까지 포함해 의도한 조합을 기록합니다.

{
  "sourceAnchorId": "right-75",
  "targetSymbol": "system:capping-station",
  "targetAnchorId": "left-75",
  "targetRotationDegrees": 0,
  "targetFlipHorizontal": false,
  "targetFlipVertical": false,
  "connectionType": "material"
}

검사는 이렇습니다. sourceAnchorId는 이 심볼 자신의 연결점 가운데 하나여야 합니다. targetSymbol은 출처가 밝혀진 참조여야 하고, 옮길 수 있는 패키지에서는 system:<stable-key>만 될 수 있으며(사용자 GUID는 그것을 가진 스테이션 안에서만 뜻이 있습니다) 시스템 카탈로그에 있으면서 targetAnchorId에 연결점을 가진 심볼을 불러야 합니다. 회전은 0, 90, 180, 270 가운데 하나이고 뒤집기 표시 둘은 모두 필수입니다. 제안은 저마다 고유해야 합니다. connectionType은 양쪽 끝의 고정된 종류가 같아서 상황이 분명할 때에만 빠뜨릴 수 있습니다. 어느 한쪽이라도 구성할 수 있으면 필수이며, 그때는 양쪽 끝에서 모두 허락되어야 합니다.

제안에는 방향이 있고 배열 순서가 우선순위를 정하지만, 평범한 대시보드 연결선의 허용 목록은 결코 아닙니다. suggestions 배열이 비어 있으면 검사기는 카탈로그 짝을 지어내는 대신 제안된 조합이 없다고 알립니다.

가져오기가 거부하는 것

실패한 가져오기를 짐작하는 대신 읽을 수 있도록, 거부를 빠르게 훑어보는 목록입니다. 평범한 SVG에는 첫 묶음만 해당하고, 그 안에서도 크기 상한과 깨진 XML과 없는 <svg> 뿌리만이 가져오기를 거부합니다. 허용되지 않은 마크업은 대신 경고와 함께 고쳐집니다. 패키지에서는 아래의 모든 것이 그대로 거부 사유입니다.

그림

• 1 MB가 넘는 파일, 512 KB가 넘는 마크업, 또는 요소 4096개가 넘는 것.
• 깨진 XML, 또는 정화된 <svg>가 아닌 뿌리.
• 패키지에서는 허용 목록이 걷어 내야 했을 모든 마크업(스크립트, 이벤트 처리기, 외부 참조, 허용되지 않은 요소나 속성).
• 너비와 높이가 양수인 유한한 숫자 넷이 아니거나 SVG 뿌리의 것과 다른 viewBox, 그리고 뿌리 뷰 박스가 아예 없는 패키지.

봉투

• v2 규약이 아닌 스키마나 형식이나 버전, 어디에든 있는 알 수 없는 칸, 없는 name이나 fit이나 footprint나 배열 셋 가운데 하나, 그리고 배열 안의 null 항목.
• 네 가지 방식 밖의 fit, 그리고 1_{24 × 1}12 밖의 크기.

가변 영역

• 식별자 문법 밖의 이름이나 요소 id, 겹치는 가변 영역 이름, SVG에 없는 대상 id, 그리고 대상 요소가 받을 수 없는 갈래(글자가 아닌 요소의 text, <line>의 fill).
• 대상에 유한한 data-ganter-pivot이 없는 rotate나 spin이나 scale 가변 영역, 그리고 같은 요소에 spin 가변 영역이 없는 spinEnabled 가변 영역.
• 한 요소의 같은 채널에 놓인 가변 영역 둘. fill과 fillColor가 채움 채널을, stroke와 strokeColor가 선 채널을 함께 쓰는 것 말고는 갈래마다 자기 채널이므로, 한 요소가 회전 둘을 받을 수 없듯 채움 둘도 받을 수 없습니다.
• 유한하지 않은 범위 숫자, 한쪽 끝만 있는 두 번째 출력이나 translate와 scale이 아닌 갈래의 두 번째 출력, 안전하지 않은 칠하기, 그리고 Logic 주소를 담은 가변 영역.

연결

• 연결점 16개를 넘는 것, 되풀이되거나 알 수 없는 앵커 id, type과 typeConfiguration을 둘 다 가지거나 둘 다 가지지 않은 연결점, 알 수 없는 종류나 구성 id, 그리고 올바르지 않은 내부 경로(뷰 박스 밖, 길이가 0이거나 각도가 어긋난 선분, 90°가 넘는 꺾임).
• 올바르지 않은 id, 없는 이름, 겹치거나 알 수 없는 허용 종류, 또는 자기 목록 밖의 기본값을 가진 종류 구성.
• 원본 연결점이 없는 제안, 대상이 그 이름의 연결점을 가진 시스템 심볼이 아닌 제안, 자세가 90° 단위가 아닌 제안, 또는 연결선 종류가 양쪽 끝에서 받아들여지지 않는 제안.

MCP 엔드포인트의 symbol_validate는 바로 이 가져오기를 시험 삼아 돌려 보고, 아무것도 저장하지 않은 채 모든 오류와 경고와 참고 사항을 알려 줍니다.

꾸리기와 나누어 쓰기

패키지 내보내기(시스템 심볼과 사용자 심볼 모두에 있습니다)는 정화된 그림과 규약 전체를 담은 <name>.ganter-symbol.json을 내려받습니다. $schema, format, version, name, svg, viewBox, fit, footprint, slots[], typeConfigurations[], terminals[], suggestions[]이며, 연결 관련 배열 셋은 비어 있어도 들어 있습니다. 결코 함께 가지 않는 것은 스테이션 주소, 인스턴스마다의 종류 선택, 데이터베이스 신원, 사용자 신원, 그리고 그 스테이션의 연결선 종류 색과 두께입니다.

받는 스테이션에서는 같은 파일이 심볼 가져오기(또는 MCP의 symbol_import)를 지나 연결점까지 그대로 새 사용자 심볼로 놓입니다. 종류의 신원이 변하지 않는 id이고 겉모습이 공통이므로, 가져온 심볼의 경로는 곧바로 받는 스테이션 자신의 연결선 종류 꾸밈을 따릅니다.