Parsing

SVG Parsing 구조 및 처리

1. 개요

본 문서는 로봇팔 시뮬레이터 프로젝트 plotto에서
SVG 파일을 입력으로 받아 로봇 동작 생성에 필요한
경로 데이터로 변환하는 SVG 파싱 과정을 설명합니다.

SVG 파싱은 시스템 전체 동작 파이프라인의 첫 단계로,
이 단계에서 추출된 경로 정보는 이후 좌표 변환,
기구학 계산 및 plotto Path 생성의 입력 데이터로 사용됩니다.

---

2. SVG 파싱의 역할

SVG는 XML 기반의 벡터 이미지 포맷으로,
다양한 요소와 속성을 포함하고 있으나
plotto 시스템에서는 경로(Path) 정보만을 선택적으로 활용합니다.

SVG 파싱 단계의 주요 목적은 다음과 같습니다.

1. SVG 파일 구조 해석
2. 경로(Path) 요소 추출
3. 경로 명령어를 좌표 기반 데이터로 변환
4. 펜 업/다운 상태를 명확히 구분

---

3. 입력 데이터 구조

3.1. SVG 파일

• 입력 형식: .svg
• 파싱 방식: XML 기반 구조 분석
• 주요 대상 요소: <path> 태그

3.2. 경로(Path) 데이터

SVG의 경로는 d 속성에 문자열 형태로 저장되며,
복수의 명령어와 좌표 정보가 순차적으로 포함됩니다.

M 10 10 L 50 50 Z
// d 속성 문자열 예시: "이동(M) → 직선(L) → 닫기(Z)"

1. 기본 구조 SVG <path> 태그는 다음과 같은 형태를 갖습니다.

   • d 속성 내부가 곧 path 데이터
   • path 문자열은 명령어 + 숫자 좌표의 반복으로 구성 예시

   <path d="M 100 100 L 200 100 L 200 200 Z" />

   • 주요 PATH 명령어

     명령어	의미	좌표 개수	예시
     M	Move to (이동)	2	M 100 100
     L	Line to (직선)	2	L 200 100
     H	Horizontal line	1	H 250
     V	Vertical line	1	V 250
     C	Cubic Bezier curve	6	C 200 200 300 300 400 400
     Q	Quadratic Bezier curve	4	Q 150 150 200 200
     S	Cubic 곡선 연속형 (이전 제어점 반사)	4	S 300 300 400 400
     T	Quadratic 곡선 연속형 (이전 제어점 반사)	2	T 200 200
     A	Arc (원호)	7	A 50 50 0 0 1 200 200
     Z	Close path (닫기)	0	Z

   • 대문자 명령어는 절대좌표(absolute), 소문자는 상대좌표(relative)를 의미합니다.

   예: l 10 0 → 현재 위치 기준으로 오른쪽으로 10 이동

2. 파싱 원리 (개념) d 문자열을 좌표 기반으로 바꾸는 기본 절차는 다음과 같습니다.

   1. d 문자열을 토큰화(tokenize)
      • 명령어 문자(M/L/C/..) 와 숫자를 분리
   2. 명령어를 만나면, 그 명령어가 요구하는 좌표 갯수만큼 숫자를 읽음
   3. 세그먼트를 구조화하여 저장

      예: { cmd: 'L', args: [200, 100] }

   4. 다음 명령어로 넘어가면서 반복

---

4. 파싱 관련 함수 (spine.js에서 정의됨)

extractPathPointsFromSvg(svgText, opts = {})

extractPathPointsFromSvg(svgText, opts={}) 함수는 SVG 이미지 소스 (svgText)를 입력으로 받아, 그 안에 포함된 모든 도형(graphic element)들의 경로를 따라 일정 간격의 점들을 추출하고 이를 좌표 리스트로 반환하는 기능을 합니다.

1. 매개 변수

   • 이 함수는 두 개의 인수를 받습니다.

   • svgText : SVG 파일의 원본 텍스트 입니다. SVG를 문자열 형태로 제공하면, 함수가 이를 파싱하여 DOM 구조로 변환합니다.

   • opts : 경로 추출과 샘플링 옵션을 담은 객체입니다. 기본값은 {}이며, 다음과 같은 속성을 지정할 수 있습니다.

2. opts 옵션

   옵션 이름	타입 / 기본값	설명
   sampleStep	number / null	샘플링 간격를 직접 지정합니다. 이 값이 주어지면 각 경로를 고정된 간격으로 샘플링하며, samplesPerPath설정은 무시됩니다.
   samplesPerPath	number / 200	각 도형의 경로를 몇 등분으로 나눌지에 대한 대략적인 기준입니다. 경로 전체를 이 값으로 나누어 평균 간격을 계산합니다.
   maxStepClamp	number / 2	샘플 간격의 상한값을 지정합니다. 너무 긴 경로의 경우 간격이 지나치게 커지는 것을 방지하기 위한 값으로, 간격이 이보다 크다면 이 값으로 고정됩니다.
   maxSamplesPerPath	number / 3000	각 경로당 생성될 수 있는 최대 샘플 점 갯수입니다.
   bridgeScale	number / 1.0	path 간 이동 경로의 밀도를 결정하는 스케일 변수입니다.

opts를 통해 경로 샘플링 간격과 밀도를 세밀하게 조정할 수 있습니다.

3. 전반적인 실행 흐름

   1. SVG 파싱 및 준비
      • 주어진 svgText 문자열을 DOM Parser를 이용해 SVG DOM 객체로 변환하고, 가상으로 사용할 <svg>엘리먼트를 추가하여 SVG의 길이를 계산합니다.
   2. 도형 요소 수집
      • SVG 내의 모든 그리기 요소(<path>, <circle>, <rect>, <line>, <polygon>, <polyline> 등)을 찾고, 표시 속성이 숨김 처리되지 않은 것만 선별합니다.
      • 이때 각 요소마다 해당 요소에 적용된 변횐 행렬(Transform)을 계산하여 함께 보관합니다.
   3. 도형별 경로 변환
      • 수집한 각 도형을 SVG <path>와 같은 형태인 경로 데이터(d)로 변환합니다. 기본 도형(<rect>, <circle>등)인 경우엔 경로 명령으로 바꾸고, 이미 <path>인 경우에는 그대로 사용하되, 내부에 MOVE 명령이 있을 경우 분리합니다.
   4. 경로 샘플링
      • 각 경로에 대해 일정 간격으로 값을 증가시키며 getPointAtLength를 이용해 좌표를 샘플링합니다. 첫 점은 펜을 들어서 이동(pen = 0)하며, 아후 점은 펜을 대고 그리는(pen = 1)상태로 샘플링하여 localPoints 리스트를 얻습니다.
   5. path 사이 보간
      • 이전 경로의 마지막 점과 다음 경로 첫점 사이에 거리가 있다면, 펜을 든 상태로 해당 간격을 이동하는 중간 점을 삽입합니다.
   6. 포인트 반환
      • 모든 경로 조각들에 대해 샘플링이 끝나면, 이들을 순서대로 points 배열에 이어붙입니다. 결과적으로 points에는 SVG의 모든 도형을 순회하는 좌표 점들이 차례대로 담기며, 각 점은 펜 상태를 가지고 있어 언제 선을 그리고 언제 이동하는지 구분됩니다.
        마지막으로 이 points 배열을 반환합니다.

4. 실행 동작

   1. SVG 파싱 및 초기 설정

      DOM 객체 생성

      • 함수는 주어진 SVG 텍스트를 파싱하여 DOM 객체를 생성합니다.
      • 이 때, DOM 파서를이용하여 실제 SVG DOM 객체로(doc)변환합니다.

   2. 임시 SVG 엘리먼트 생성

      • 브라우저 환경에서 SVG 경로 길이 및 좌표 계산 API를 활용하기 위해 임시 <svg>요소를 동적으로 생성합니다. 이렇게 하는 이유는, SVG DOM의 getTotalLength() 및 getPointAtLength() 메소드는 SVG 요소가 DOM에 있어야 정상 동작하기 때문입니다.

   3. 변수 초기화

      • 최종으로 반환할 배열인 points를 초기화합니다.(point에는 {x, y, pen} 객체가 순서대로 쌓입니다.) 또한, 이전 도형의 마지막을 저장하는 lastGlobalPt도 초기화합니다.(첫 도형 후에 값을 채웁니다.)
      • 이 값은 path 간 이동 경로를 계산하기 위해 사용됩니다.

5. 변환 행렬 유틸리티

   SVG 요소들은 transfrom 속성을 통해 평행이동, 회전, 스케일, 기울이기(skew)등의 변환을 가지며, <g> 그룹을 이용해서 상위 그룹들의 변환이 누적 적용 될 수 있습니다. spine 코드에선 이러한 변환을 적용하기 위해 변환 affine 행렬을 이용해서 좌표계 경로를 구하며, 이 행렬 유틸리티 함수에 대해 소개하고자 합니다.

   1. I()

      • 항등 행렬{a:1, b:0, c:0, d:1, e:0, f:0}을 반환합니다(a=1, d=1이고 나머지 0인 단위행렬)

   2. T(tx, ty)

      • 이동 행렬을 반환합니다. x방향 tx, y 방향 ty만큼 평행이동 시키는 행렬입니다.

   3. S(sx, sy)

      • 스케일 행렬을 반환합니다. x축 방향 sx배 y축 방향 sy배 확대/축소 합니다.

   4. R(deg)

      • 회전 행렬을 반환합니다. 주어진 각도 만큼 원점을 중심으로 회전하는 행렬입니다.

   5. KX(deg)

      • X축 기준 기울이기 행렬을 반환합니다. 주어진 각도 만큼 x축 방향으로 기울이는 변환입니다.

   6. KY(deg)

      • Y축 기준 기울이기 행렬을 반환합니다. 주어진 각도 만큼 y축 방향으로 기울이는 변환입니다.

   7. multiplyMatrices(m1, m2)

      • 두개의 행렬 m1,m2를 받아 순서대로 합성한 결과 행렬을 반환합니다.

   8. parseTransform(transformStr)

      • "translate(...)", "rotate(...)"와 같은 SVG transform 속성 문자열을 읽어들이고, 그 변환들의 합성 결과를 하나의 행렬로 변환하는 함수입니다.

      예를 들어, transform="translate(10, 5) rotate(30)"와 같은 문자열을 파싱하여 하나의 행렬 객체로 반환합니다.

      • 정규식으로 "이름" 패턴을 찾아서 각 변환명령을 순서대로 해석하며, 앞서 정의한 행렬 함수들을 이용합니다.
      • 각 변환 행렬 m을 이전까지의 누적 행렬 M에 곱셈하며 합성해 나갑니다. 이렇게 하면 transform 문자열에 나열된 변환이 순차 적용된 최종 행렬 M을 얻게 됩니다.

   9. getAccumulatedTransformInclusive(el)

      • <g>그룹에 속한 svg는 자신의 transform을 포함하여 부모를 따라 최상위 svg까지 거슬러 올라가며 모든 변환을 합성해야 합니다.
        이 함수는 요소 자체 -> 부모의 변환 .. 순으로 모두 곱한 전체 변환 행렬을 반환합니다.

   10. getAccumulatedTransformParentsOnly(el)

       • <use> 요소를 구할 때, 자기 자신의 transform을 적용하기 전 상위 요소의 transform을 적용해야 합니다.
         이 함수는 요소 자체의 변환을 제외하고 부모들의 누적 변환을 구하여 반환합니다.

   11. shouldRender(el)

       • 실제로 그려지지 않는 요소를 제외하는 필터 함수입니다.
         

       예를 들어, <defs>, display="none"와 같은 요소는 그려지지 않는 요소인데, 이와 같은 것을 제외합니다.

6. 도형을 경로 데이터(path)로 변환

   SVG내에는 path 요소 외에도 <circle>,<rect> 등 다양한 기본 도형이 있습니다. 이 함수에서는 모든 도형을 path 데이터로 변환하여 처리합니다. 또한, 하나의 <path>요소에도 moveTo(M)으로 pen이 0이 되는 부분이 있는데,그 path도 각각 따로 변환합니다.

   1. splitSubpathsFixed(dAttr)

   • 이 함수는 svg <path>의 d 속성 값을 파싱하여 여러개의 서브 패스로 분리하는 기능을 담당합니다.

     1. 입력 문자열 토큰화

        • dAttr 문자열을 정규표현식을 사용하여 토큰화 해 한글자의 명령 문자(M,I,C)와 숫자 토큰으로 분리합니다.

        예를 들어, 예를 들어 "M10 10 L20 20"라는 문자열은 ["M", "10", "10", "L", "20", "20"]처럼 분해됩니다.

        • 명령어 별 파라미터 개수 정의 : PARAMS 맵에 각 명령마다 요구되는 좌표 값의 갯수를 미리 정의해 둡니다. 이 맵을 바탕으로 각 명령에서 몇개의 토큰을 읽어야 하는지 판단합니다.

     2. 상태 변수 초기화

        • 경로의 현재 상태를 추적하기 위해 몇가지 변수를 사용합니다. cx, cy는 현재점의 좌표로, 초기값은 (0,0)입니다. sx,sy는 서브패스의 시작점으로, 새로운 서브 패스가 시작될 때 갱신되어 Z 명령 처리에 사용됩니다. out배열은 결과로 반환하라 서브패스 문자열을 담는 리스트이며, buf배열은 서브패스의 경로 데이터를 임시로 누적하는 버퍼입니다. hasSubPath는 현재 누적중인 서브패스가 있는지 나타내며, lastCmd변수에서는 직전에 처리한 명령을 저장하는 역할을 합니다.

     3. 헬퍼 함수 정의

        • isCmd(token) : 주어진 토큰이 명령 문자인지(a ~ z 또는 A ~ Z) 확인하는 함수입니다.
        • flush() : 현재 buf에 누적된 서브패스 데이터를 out 결과 리스트에 추가합니다. 추가 후에는 buf를 빈 문자열로 초기화하고 hasSubpath를 false로 리셋하여 새로운 서브패스를 시작할 준비를 합니다.
        • readNums(n) : 현재 토큰 위치로부터 숫자 n개를 읽어 배열로 반환합니다. 이 함수에서 토큰을 읽을 시 전역변수 i를 사용합니다.
        • emit(cmd, nums) : 하나의 SVG 명령과 해당 좌표 숫자들을 buf에 추가하는 함수입니다.

     4. 메인 파싱 루프

        1. 토큰화 된 명령 목록을 순회하며 실제 파싱을 진행합니다. isCmd(cmd)를 사용하여 현재 토큰이 명령 문자인지 확인하고, 맞다면 이를 lastCmd로 설정하고 i를 증가시킵니다. 만약 현재 토큰이 숫자이고 lastCmd가 존재한다면 명령이 반복되는 중 이므로, cmd = lastCmd로 간주합니다.

        2. 명령 종류에 따른 처리

           • 식별된 cmd에 따라 서로 다른 처리를 수행합니다.

             • (Z)의 경우 : 이 명령의 경우 서브패스를 종료하고 닫는 역할을 합니다. haSubpath = false라면 닫을 서브패스가 없는 것 이므로 무시하고 넘어가며, 서브패스가 진행중인 중이라면, emit("Z")를 호출하여 buf에 "Z"를 추가합니다. 그리고 현재점을 해당 서브패스의 시작점으로 되돌립니다 (cx = sx; cy = sy;).
             • (M/m)의 경우 : moveto 명령을 만나면 새로운 서브패스를 시작합니다. hasSubpath = true라면 flush()를 호출해 이전 서브패스를 끝낸 후, 새 서브패스를 시작합니다. 이후 readNums(2)을 통해 두 숫자를 읽어 새로운 이동 좌표(x,y)를 가져옵니다.

           • 좌표를 얻었다면, M(절대 좌표 이동)과 m(상대 좌표 이동)에 따라 처리합니다.

             • m의 경우 : 현재점(cx, cy)를 기준으로 오프셋을 적용해 절대 좌표를 계산합니다. mx = cx + x; my = cy + y로 새 절대 위치를 구한 뒤, 이를 실제 이동 명령으로 변환합니다.
             • M의 경우 : 읽은 좌표를 그대로 사용합니다.

           이후 emit("M", [mx, my])를 호출하여 새로운 서브 패스 시작을 M 명령으로 buf에 기록합니다. 또한, 새로운 서브패스가 시작되었으므로 hasSubpath를 true로 설정하고, 현재점 cx, cy를 (mx, my)로 갱신합니다. 또한 sx, sy에 이 좌표를 저장하여 서브패스 시작점을 기록합니다.

           • LineTo 처리
             • moveto 명령 뒤에 추가 좌표 쌍들이 나열되면 자동으로 연속된 직선 그리기(line-to) 명령들로 해석됩니다.
             • 이를 코드에서 처리하기 위해 첫 좌표 쌍 처리 이후 반복문을 통해 다음 도큰을 확인하여 숫자라면 동일 서브패스 내의 추가 선그리기로 판단합니다.
             • 첫 좌표 쌍 처리에서 원본 명령이 m(상대)였다면, 선 명령은 l로 판단하고, M(절대)였다면 선 명령을 L로 판단합니다.
             • moveto 및 LineTo 처리가 끝나면 continue를 통해 M/m 분기가 종료됩니다.
           • 그외의 명령(L,H,V,C 등)
             • 나머지 그리기 명령에 대해선 해당 명령이 필요로 하는 숫자 파라미터를 PARAMS에서 구한 뒤, 내부 반복문을 통해 명령과 관련된 숫자를 처리합니다. 이후 하나의 좌표 세트를 처리한 후엔 (cx,cy)를 업데이트 합니다.
             • 각 세트 처리 후에는 hasSubpath = true로 처리합니다. 이렇게 메인 루프를 실행하고, 종료 후에는 buf에 남아있는 서브 패스 데이터를 flush()를 통해 호출하여 out에 추가합니다.

   • 최종적으로 각 원소가 독립된 서브패스 경로 문자열인 out 배열을 반환합니다.

   예를 들어, 입력 dAttr가 "M0 0 L10 0 L10 10 Z M20 20 L30 30" 였다면, 이 함수는 두 개의 서브패스로 분리하여 다음과 같은 배열을 반환합니다: - ["M 0 0 L 10 0 L 10 10 Z", "M 20 20 L 30 30"]

   2. circleToPathLocal(cx,cr,y)

      • 원은 path로 변환하기 위해 두개의 호로 표현합니다. svg path의 A(원호) 명령을 이용하여 두개의 호로 원을 구성합니다. <circle>요소의 cx, cy, r 속성을 읽어 중심 좌표와 반지름을 얻습니다.
      • 원의 가장 왼쪽점에서 시작(M x0,y 형식, x0 = cx - r)하여 우측으로 반원을 그리는 아크 명령 A를 사용하고, 다시 좌측으로 돌아오는 두 번째 아크 명령을 추가하여 닫는 식입니다. 마지막에 Z로 경로를 닫아 완전한 원을 표현합니다.
      • 이 방식으로 원을 SVG path의 A 명령으로 표현할 수 있습니다.

   3. ellipseToPathLocal(cx, cy, rx, ry)

      • 타원은 4개의 베지어 곡선으로 근사하여 경로로 변환합니다.

      • 구현에서 사용된 K = 0.5522...는 원이나 타원을 4개의 곡선으로 근사할 때 사용되는 카파(kappa) 상수로, 이 상수를 사용하면 베지어 곡선의 중점이 실제 원에 거의 근접하도록 제어점의 거리를 결정할 수 있습니다.

      • 이 함수는 우선 주어진 rotation 값을 고려해 미리 회전 변환을 적용합니다. 이후 타원의 4개의 주요 점과 베지어 제어 점도 회전하여 구합니다.

      • 그런 뒤에, 경로 문자열을 구성합니다. M 명령으로 시작하여 left 점으로 이동하고, 이어서 C 큐빅 베지어 명령을 사용하여 top 점까지 곡선을 그리도록 제어점 c1, c2를 지정합니다.

      • 같은 방식으로 연속된 3개의 C 명령을 사용하여 top->right, right->bottom, bottom->left로 이어지는 곡선들을 추가합니다. 마지막에 Z로 닫아서 하나의 연속된 패스로 타원을 근사합니다.

   4. rectToPathLocal(x, y, width, height, rx, ry)

      • 사각형은 rx, ry(모서리 반경)에 따라 두가지 방식으로 처리합니다.

      공통 처리

      • x, y, width, height, rx, ry 속성을 읽습니다. 여기서 rx, ry가 없으면 0으로 처리하고, 하나만 지정된 경우 두 값을 동일하게 맞춥니다. 또한, rx > width / 2 이면 width / 2로 제한하고, ry > height / 2 이면 height / 2로 제한합니다.

      모서리가 둥근 사각형(rx > 0 && ry > 0)

      • rx > 0 이고 ry > 0 인 경우, 각 모서리를 타원 1/4 호에 근사한 베지어 곡선으로 처리합니다.
      • 원의 1/4을 큐빅 베지어로 근사하기 위해 K = 0.5522... 상수(카파 상수)를 사용하며, 각 모서리에 대해 ox = rx _ K, oy = ry _ K 값을 계산합니다.
      • 직선(L)과 큐빅 베지어(C) 명령을 조합하여 네 모서리를 부드럽게 연결합니다. 이후 네 모서리를 모두 연결한 후 Z 명령으로 경로를 닫습니다.

      이 결과, 원래 rect의 둥근 모서리를 rx, ry 반지름의 타원 호에 근접한 path로 변환합니다.

      모서리가 직각인 사각형(rx <=1e-9 && ry <=1e-9)

      • M x,y로 시작한 뒤, 시계 방향으로 네 개의 L 명령을 사용해 꼭짓점을 연결합니다.
        마지막에 Z 명령으로 경로를 닫아 단순 사각형 path를 생성합니다.

   5. lineToPathLocal(x1, y1, x2, y2)

      • <line> 요소는 시작점 (x1, y1)과 끝점 (x2, y2)을 가지는 단순 선분입니다.

      M x1,y1 → L x2,y2 형태의 path로 변환합니다.

   6. polyToPathLocal(pointsStr, close)

      • <polygon>, <polyline> 요소의 points 속성을 파싱하여 좌표 배열을 얻습니다. 첫번째 점을 M 명령으로 설정하며, 이후 각 점마다 L 명령을 추가하여 직선을 그립니다. 마지막에 close가 true이면(<polygon>의 경우) Z를 붙여 닫고, false 이면(<polyline>의 경우) 열린 채로 둡니다.

      결과적으로 polygon / polyline도 path 데이터로 변환됩니다.

   위의 각 도형 변환 함수를 통해 SVG 기본 도형 요소들이 모두 경로 문자열(path)로 변환됩니다. 이 때, 원본이 path인 경우에는 splitSubpaths함수를 통해 여러 조각으로 나뉘어 질 수 있습니다.(path 안에 M이 두번 이상 있는 경우.)

7. <use> 요소 처리

   • svg에서는 <use xlink:href="#id">와 같은 형태로 사전에 정의된 도형을 복사하여 쓸 수 있습니다.
   • <use>는 xlink:href 또는 최근 href 속성으로 참조 대상의 id를 가리키며 x, y 등의 속성으로 위치를 조정하거나 자체적으로 transform을 가질 수도 있습니다.
   • extractPathPointsFromSvg() 함수에선 resolveUseElement(useEl)가 그 처리을 담당합니디.

   1. resolveUseElement(useEl) 함수

      • 이 함수는 <use> 요소의 원본 도형 + 여러 단계의 변환을 모두 해석해 하나의 실제 도형으로 변환한 뒤 렌더링 대상에 포함시키는 과정을 거칩니다.

      • <use>의 href 속성에서 참조 대상 추출

        • <use> 요소의 href 또는 xlink:href 값을 읽어 #id 형태의 참조 대상 id를 추출하고, svgRoot.querySelector('#id')로 원본 그래픽 요소를 찾습니다.

        • 원본 요소 존재 확인 : 만약 참조된 id에 해당 원본 요소가 존재하지 않으면, 건너뜁니다.

      • <use>요소의 x, y 속성을 평행이동 행렬로 변환

        • <use> 요소의 x,y 속성을 읽어 (x,y)로 이동시키는 평행이동 행렬 T로 변환합니다.

      • 변환 행렬 수집

        • <use>로 인해 적용되는 모든 변환을 다음 네가지 종류로 분리하여 수집합니다.

        구분	설명
        부모 그룹 변환	<use> 요소의 상위 <g> 요소들에 적용된 transform을 누적한 변환 행렬
        <use> 자체 변환	<use> 요소에 직접 지정된 transform 속성으로부터 생성된 변환 행렬
        <use> 위치 이동	<use> 요소의 x, y 속성으로부터 생성된 평행이동(translate) 행렬
        원본 요소 변환	<use>가 참조하는 원본 그래픽 요소(ref)에 적용된 transform 속성으로부터 생성된 변환 행렬

      • 최종 변환 행렬 합성

        • 수집된 변환 행렬을 부모 -> <use> 자체 변환 -> <use> 위치 이동 -> 원본 요소 변환 순으로 적용하여 하나의 행렬로 합성합니다.

      • <use> 해석 결과 객체 생성

        • 해석된 <use> 요소에 대해 다음 정보를 포함하는 객체를 생성합니다.

      • 반환값으로는 { element: ref, transform: M, tagName: ref.tagName.toLowerCase() } 객체를 생성하여 리턴합니다.

   • 요약하면, <use> 요소는 내부에서 참조된 도형을 찾아 복제한 뒤 위치/변환을 적용해주는 형태로 다루며, 그렇게 변환된 도형은 실제 <path>나 <circle> 등과 동일하게 이후 과정(경로 변환, 샘플링 등)을 거치게 됩니다.

8. 그래픽 요소

   • SVG 내부의 각 도형 요소들을 수집하고, 각 요소 별로 경로 정보를 준비합니다. 이 때, 크게 두가지 요소를 다루는데, 직접적인 그래픽 요소(path와 기본 도형)와 <use>참고 요소 입니다.
   • 기본 그래픽 요소 처리
     • svgRoot.querySelectorAll("path, circle, rect, ellipse, line, polygon, polyline")를 이용하여 svg 내 모든 기본 그래픽 요소를 선택합니다.
     • 이 때, shouldRender(el)를 통해 렌더링 대상인지 확인하고, 맞다면 allElements 배열에 추가합니다. 이 때, 추가 시에 요소의 정보도 같이 저장합니다.

   allElements.push({
   element: el, // 요소
   transform: getAccumulatedTransformInclusive(el), // 누적 변환 행렬
   tagName: el.tagName.toLowerCase(), // 태그 명
   });

   • <use> 요소 추가
     • svgRoot.querySelectorAll("use")를 통해 모든 <use>요소를 순회하며 shouldRender로 표시 여부를 검사한 뒤, 표시 대상이면 위에서 설명한 resolveUseElement(useEl)를 호출합니다. resolveUseElement가 유효한 객체(참조 성공)를 반환하면, 이를 allElements에 추가합니다.

   이 과정들을 거치면 allElements 배열에는 SVG에 실제 그려질 모든 도형 요소들이 추가되게 됩니다.

9. 경로 길이 계산

   • 도형별로 얻은 경로 데이터를 정리하고 길이를 구하는 단계입니다. allElements 리스트를 이용하여 다음과 같이 처리합니다.

   각 경로의 길이를 구하는 이유는, 점 샘플링 간격을 결정하고 최적화 하기 위해서입니다.

   • 객체 값 꺼내기 및 배열 초가화

     • 객체에서 element, tagName, transform을 꺼냅니다. 이후 경로 데이터를 담을 dList 배열도 초기화합니다. 또한, 최종 경로 객체를 담을 prepared 배열도 초기화합니다.

     이후 요소의 종류별로 분기하여 경로 데이터를 얻습니다.

   • 요소 별 분기

     • path 일 경우 : 이미 경로 데이터를 가지고 있는 요소로, 문자열을 가져 온 뒤, splitSubpathsFixed()를 호출하여 필요 시에 여러 하위 경로로 분할합니다. splitSubpathsFixed()의 결과를 dList 배열에 담습니다.
     • circle인 경우 : circleToPathLocal(cx, cy, r)을 호출하여 경로 문자열을 생성하고, 이를 dList에 추가합니다.
     • ellipse인 경우 : ellipseToPathLocal(cx, cy, rx, ry, rotation)을 호출합니다. 여기서 rotation 각도는 특별히 계산하는데, transformMatrix가 존재할 경우 행렬로부터 회전 성분을 추출하여 사용합니다. 코드에서는 행렬 m의 a,b 값을 이용해 rotation = atan2(m.b, m.a) * (180/Math.PI)로 각도를 얻는데, 이는 행렬의 변형이 순수 회전/스케일 조합일 때 그 회전 각도를 근사합니다.
     • rect인 경우 : rectToPathLocal(x, y, width, height, rx, ry) 호출 결과 경로 문자열을 dList에 추가합니다.
     • line인 경우 : lineToPathLocal(x1, y1, x2, y2) 결과 문자열을 넣습니다.
     • polygon / polyline 인 경우 : polyToPathLocal(points, true) / polyToPathLocal(points, false) 호출히여 경로 문자열을 dList에 추가합니다. 이렇게 해서 dList에 한 요소로부터 유래된 하나 이상의 d 문자열이 들어갑니다.

   • 경로 길이 측정

     • dList를 순회하며 하나의 임시 <path> 요소 pathEl를 생성하고 pathEl.setAttribute("d", dAttr);로 경로 데이터를 설정합니다.
     • 만약 해당 요소에 transformMatrix가 있다면 적용합니다. 이후 pathEl.getTotalLength()를 통해 전체 길이를 구합니다. 길이를 얻었다면 pathEl.getTotalLength()로 임시 path를 제거하고, prepared 리스트에 객체를 추가합니다. prepared.push({ dAttr, transformMatrix, length: L });

   이제 prepared에 경로 데이터와 길이가 모이게 되고, 이 정보에 기반하여 점 샘플링을 수행합니다.

10. 점 샘플링

    • prepared에 담긴 각 경로를 따라 일정한 간격으로 점을 찍어 points 배열에 누적합니다. 샘플링 단위는 opts와 경로의 길이에 의해 결정되고, 각 도형의 bridge 부분도 함께 처리됩니다.

• 샘플링 루프 시작

  • prepared 배열을 순회하면서 각 항목(item)에 대해 처리합니다. 우선 임시 <path>요소 pathEl를 생성하고 dAttr를 설정합니다. 이후 임시 svg에 대해 transformMatrix가 있다면 적용합니다. 이후 tempSvg.appendChild(pathEl);로 임시 SVG DOM에 추가합니다.

• 샘플링 간격 설정

  • 옵션으로 sampleStep이 주어졌다면, step = sampleStep으로 설정합니다. sampleStep이 없다면, 이 경로의 길이를 samplePerPath로 나눈 값으로 step을 정합니다.

  이 때, 이렇게 계산한 step이 maxStepClamp보다 큰 경우, step = maxStepClamp로 상한을 제한합니다.(너무 간격이 커지는 것을 방지)

• 최대 점 수 제한

  • 경로가 매우 길어서 step 간격으로 찍으면 점 개수가 maxSamplePerPath를 초과할 경우, 간격을 조금 늘려 점 개수를 제한합니다.

  이 과정으로 최종 step이 결정됩니다.

• 경로를 따라 점 찍기

  • 이제 루프를 돌며, 경로를 시작부터 끝까지 step 간격으로 따라가면서 좌표를 샘플링합니다.
  • len에 step을 더해가면서 루프가 진행되며, pathEl.getPointAtLength(len)를 통해 len 거리만큼 떨어진 지점의 좌표를 객체로 반환하고, isFirst가 true일시, pen을 0, 아닐 시 pen을 1로 처리하여 localPoints에 저장합니다.이후 isFirst를 false로 변경합니다

  이로써, path 첫 점 이후는 모두 pen 1로 처리됩니다.

  • 또한, 루프 종료 후, 별도로 pathEl.getPointAtLength(totalLength)를 호출하여 경로의 마지막 점을 얻고, 이를 localPoints에 추가합니다.

• 임시 path 제거

  • 사용이 끝난 pathEl은 다시 tempSvg.removeChild(pathEl)로 제거합니다. 이는 경로 겹침 문제를 피하고, 메모리 소비를 줄이기 위해서 입니다.

• 도형 간 bridge 추가

  • 한 도형의 점을 points에 추가하기 전에, 만약 이전 도형의 마지막 위치가 있을 경우(lastGlobalPt가 null이 아닌 경우)
    그 점에서 현재 새 경로의 첫 점까지 펜을 들어 이동하는 경로를 추가로 샘플링합니다. bridge 샘플링 밀도는 기본 step에 opts.bridgeScale를 곱해 조절합니다. bridgeStep = step * bridgeScale` bridge 구간은 펜을 든 이동이므로, pen은 0으로 기록합니다.

• 점 누적 및 lastGlobalPt 갱신

  • 이제 브리지 점(만약 있다면)이 points에 추가된 상태에서, 현재 도형의 실제 경로 점들(localPoints 배열)을 순서대로 points 배열에 이어붙입니다.
  • 이후 lastGlobalPt를 localPoints의 마지막 점으로 업데이트 합니다. 모든 prepared 항목에 대해 위 과정을 마치면, points 배열에는 SVG의 모든 도형 경로를 따라 생성된 점이 순서대로 담기게 됩니다.
  • 마지막으로 tempSvg (임시로 만들었던 보조 SVG 요소)를 document.body.removeChild(tempSvg)로 제거하여, 화면에 보이지 않게 생성했던 요소를 정리합니다. 그리고 points 배열을 return하여 함수 결과를 내보냅니다.

11. 출력 결과

    이 함수의 반환값 points는 다음과 같은 javascript 배열입니다.

    [
       { x: Number, y: Number, pen: Number },
       { x: Number, y: Number, pen: Number },
       ...
    ]

    이 결과를 통해, 좌표 -> 로봇의 step 증분값 으로 바꾸는 처리를 거처, 로봇이 이용 가능한 명령으로 변경하게 됩니다.