Spline Editor (SplineEditor) - ComfyUI-KJNodes

⚠️ 진행 중
아직 워크플로의 일부로 신뢰하지 마십시오.
많은 버그가 포함되어 있을 수 있으며 안정성은 보장되지 않습니다!!

다양한 스케줄 및/또는 마스크 배치를 위한 값 생성을 위한 그래픽 편집기

기술 구현 측면에서 Spline Editor 노드는 다양한 샘플링 방법(예: 경로 길이 또는 시간 기준)과 보간 알고리즘(예: Cardinal, Basis 등)을 지원하여 제어점 간의 부드러운 전환을 계산합니다.

Spline Editor는 스플라인 곡선을 생성하고 편집하는 노드입니다. 사용자가 일련의 제어점을 정의하여 부드러운 경로나 수치 시퀀스를 생성할 수 있습니다. 이 노드의 핵심 기능은 이러한 점들을 이미지 처리에 사용할 수 있는 마스크(Mask)나 일련의 FLOAT 값으로 변환하여, 후속 애니메이션이나 가중치 제어를 위한 기초 데이터를 제공하는 것입니다.

편집 컨트롤

Shift + 클릭으로 끝에 제어점을 추가합니다.
Ctrl + 클릭으로 두 점 사이에 제어점(세분화)을 추가합니다.
점을 우클릭하면 삭제됩니다(첫 번째/마지막 점은 삭제할 수 없음).
캔버스를 우클릭하면 컨텍스트 메뉴가 나타납니다:
- 새 스플라인 추가 – 동일한 캔버스에 새 스플라인을 생성합니다. 이 경로는 현재 좌표로만 출력됩니다.
- 단일 점 추가 – 현재 위치 좌표를 반환하는 단일 점을 생성합니다.
- 스플라인 삭제 – 현재 선택한 스플라인을 삭제합니다(경로를 클릭하거나 "다음 스플라인" 옵션을 통해 스플라인 순환).
순수 시각적 옵션(출력에 영향을 주지 않음):
- 핸들 가시성 전환
- 샘플 점 표시 – 반환될 점을 보여줍니다.

points_to_sample 값은 그려진 스플라인 자체에서 반환되는 샘플 수를 설정합니다. 이는 실제 제어점과는 독립적이므로 보간 유형이 중요합니다.

sampling_method:

time – 시간 축을 따라 샘플링(스케줄용)
path – 경로 자체를 따라 샘플링(좌표에 유용)
controlpoints – 제어점만 샘플링
speed – 경로를 따라 속도 기반 샘플링

output types:

mask batch – 마스크를 허용하는 노드와 호환
list of floats – IPAdapter 가중치 등과 호환
pandas series – Fizz의 Batch Value Schedule 노드와 호환
torch tensor – 알 수 없는 노드와 호환

노드 기능

기술 구현 관점에서, 이 노드는 다양한 샘플링 방법(예: 경로 길이 또는 시간 기준)과 보간 알고리즘(예: Cardinal, Basis 등)을 지원하여 제어점 간의 부드러운 전환을 계산합니다. STRING 형식의 좌표점 데이터를 입력받으며, 사용자가 정의한 캔버스 크기(mask_width 및 mask_height)에 해당하는 그레이스케일 마스크 이미지나 수치 리스트를 생성할 수 있고, 출력 결과를 지정된 횟수만큼 반복하도록 지원합니다.

노드 파라미터 설명 - Spline Editor

연결 입력 (Inputs)

파라미터 이름	데이터 타입	필수	설명
`points_store`	STRING	예	points_store: 제어점 좌표 데이터를 저장하고 전달하는 데 사용되는 STRING입니다. 일반적으로 노드 인터페이스 상호작용을 통해 내부 정의 형식으로 생성됩니다.
`coordinates`	STRING	예	coordinates: 제어점의 좌표 시퀀스를 "x1,y1,x2,y2..." 형식의 STRING으로 직접 입력합니다.
`bg_image`	IMAGE	아니요	bg_image: 선택적으로 배경 이미지를 입력합니다. 노드는 이 이미지의 크기에 따라 마스크를 생성하며, 수동으로 설정한 너비와 높이 파라미터를 덮어씁니다.

컨트롤 파라미터 (Parameters)

파라미터 이름	데이터 타입	필수	기본값	범위/옵션	설명
`sampling_method`	COMBO	예	`time`	`"path"`, `"time"`, `"controlpoints"`, `"speed"`	값 생성 로직을 결정합니다. 옵션에는 time, controlpoints, speed, path가 있습니다.
`interpolation`	COMBO	예	`cardinal`	`"cardinal"`, `"monotone"`, `"basis"`, `"linear"`, `"step-before"`, `"step-after"`, `"polar"`, `"polar-reverse"`, `"bezier"`	생성되는 곡선의 부드러움과 형태에 직접적인 영향을 미칩니다. 옵션에는 cardinal, monotone, basis, linear, step-before, step-after, polar, polar-reverse, bezier가 있습니다.
`float_output_type`	COMBO	예	`list`	`"list"`, `"pandas series"`, `"tensor"`	FLOAT 출력 형식을 지정합니다. list, pandas series, tensor 중에서 선택하여 다양한 다운스트림 처리 노드에 적응할 수 있습니다.
`mask_width`	INT	예	`512`	`8` – `4096` (간격: `8`)	mask_width: 출력 마스크 이미지의 너비를 설정합니다. 범위 8~4096, 간격 8. 사용 시나리오의 이미지 너비와 일치해야 합니다.
`mask_height`	INT	예	`512`	`8` – `4096` (간격: `8`)	mask_height: 출력 마스크 이미지의 높이를 설정합니다. 범위 8~4096, 간격 8. 사용 시나리오의 이미지 높이와 일치해야 합니다.
`points_to_sample`	INT	예	`16`	`2` – `1000` (간격: `1`)	points_to_sample: 스플라인 곡선에서 샘플링할 점의 수를 설정합니다. 범위 2~1000. 점이 많을수록 곡선 표현이 더 정밀해집니다.
`tension`	FLOAT	예	`0.5`	`0.0` – `1.0` (간격: `0.01`)	tension: Cardinal 보간 알고리즘의 장력을 조정합니다. 범위 0.0~1.0, 간격 0.01. 곡선이 제어점을 통과하는 팽팽한 정도에 영향을 미칩니다.
`repeat_output`	INT	예	`1`	`1` – `4096` (간격: `1`)	repeat_output: 출력 시퀀스(예: 마스크 리스트)의 반복 횟수를 제어합니다. 범위 1~4096. 루프나 시퀀스 확장을 빠르게 생성하는 데 사용됩니다.
`min_value`	FLOAT	아니요	`0.0`	`-10000.0` – `10000.0` (간격: `0.01`)	출력 실수 값을 재매핑하기 위한 선택적 하한입니다.
`max_value`	FLOAT	아니요	`1.0`	`-10000.0` – `10000.0` (간격: `0.01`)	출력 실수 값을 재매핑하기 위한 선택적 상한입니다.

출력

파라미터 이름	데이터 타입	설명
mask	MASK	mask (출력 파라미터): 출력되는 그레이스케일 마스크 이미지입니다. 흰색 영역이 스플라인 경로를 나타냅니다.
coord_str	STRING	coord_str (출력 파라미터): 모든 샘플링된 점의 좌표 정보를 포함하는 출력 STRING입니다.
float	FLOAT	float (출력 파라미터): 스플라인 곡선을 따라 샘플링된 값을 나타내는 출력 FLOAT 시퀀스입니다.
count	INT	count (출력 파라미터): 실제 샘플링된 점의 수를 나타내는 출력 INT입니다.
normalized_str	STRING	normalized_str (출력 파라미터): 정규화된 샘플링 점 좌표 정보를 포함하는 출력 STRING입니다.

사용 시나리오

실제 응용에서, 이 노드는 동적 마스크나 제어 파라미터 곡선을 구성하는 데 자주 사용됩니다. 예를 들어, 비디오 프레임 처리 워크플로에서 사용자가 운동 경로를 그리면, Spline Editor는 해당 경로를 따른 마스크 시퀀스를 생성하여 후속 노드에서 이미지 콘텐츠(예: 입자나 라이트)의 이동 궤적을 유도하는 데 사용되어 복잡한 애니메이션 효과를 생성할 수 있습니다.

주의사항

입력 좌표점의 STRING 형식이 정확해야 하며, 정의된 캔버스 크기가 최종 사용되는 이미지 크기와 일치해야 합니다. 그렇지 않으면 생성된 마스크가 어긋날 수 있습니다. 또한, 곡선의 부드러움을 보장하기 위해 샘플링 점 수는 너무 낮게 설정하지 않는 것이 좋습니다.

Spline Editor 노드 소스코드 링크

Spline Editor 노드는 ComfyUI-KJNodes 노드 패키지에서 가져왔습니다.

Spline Editor(SplineEditor)

Spline Editor