Plot Bos Com Xy Gif

기본값으로 아래가 적용된다.

• --csv output/all_trials_timeseries.csv
• --event_xlsm data/perturb_inform.xlsm
• --rotate_ccw_deg 90
• --fps 20, --frame_step 1, --dpi 180
• --save_gif 기본 True (--no-save_gif로만 비활성화 가능)
• BOS 모드는 live-only이며 freeze 출력은 생성하지 않음

2) right1col GIF 생성 (--step_vis none)

conda run -n module python scripts/plot_bos_com_xy_sample.py \
  --subject 이재유 --velocity 20 --trial 1 \
  --step_vis none

3) Nonstep(또는 footlift) trial GIF 생성

conda run -n module python scripts/plot_bos_com_xy_sample.py \
  --subject 조민석 --velocity 30 --trial 6 \
  --step_vis phase_bos

입력 요구사항

CSV: output/all_trials_timeseries.csv

scripts/plot_bos_com_xy_sample.py는 아래 컬럼이 최소로 필요하다.

• Trial key: subject, velocity, trial
• Time index: MocapFrame
• Events (trim 구간/마커): platform_onset_local, platform_offset_local, step_onset_local
• COM: COM_X, COM_Y
• BOS 사각형 bounds: BOS_minX, BOS_maxX, BOS_minY, BOS_maxY

옵션 컬럼:

• time_from_platform_onset_s가 있으면 GIF 좌상단 패널에 시간(t=... s)을 함께 출력한다.

필수 컬럼 누락 시 즉시 에러로 종료한다. (입력 CSV가 “pipeline 결과물”이므로, 이 스크립트는 입력 보정을 하지 않는다.)

XLSM(상태 표시용): data/perturb_inform.xlsm

--show_trial_state가 켜져 있으면(기본 True) platform 시트의 아래 컬럼을 읽어서 title subtitle로 표시한다.

• subject, velocity, trial, state

state는 아래 값을 기대한다.

• step_R, step_L, nonstep, footlift

값이 다르거나 매칭 행이 없으면 경고 후 trial_type=unknown으로 표시한다. (플롯 생성 자체는 진행)

Trial 선택 규칙 (중요)

• --subject --velocity --trial을 모두 주면 해당 trial을 그린다.
• 일부만 주면 에러로 종료한다 (모호성 방지).
• 셋 다 미지정이면 (subject, velocity, trial) 정렬 기준 “첫 trial”을 자동 선택한다.

좌표/축/뷰(회전) 규칙

• 이 스크립트는 “표시용(display) 좌표”를 따로 만든다.
• --rotate_ccw_deg로 화면을 CCW(반시계)로 0/90/180/270도 회전할 수 있다.
• 기본값은 --rotate_ccw_deg 90이며, 플롯 title에 view=CCW90처럼 명시된다.

회전은 “데이터 자체 수정”이 아니라, 플롯 표시를 위해 COM과 BOS bounds 모두에 동일 변환을 적용한다.

• 회전 로직: scripts/plot_bos_com_xy_sample.py:359 (rotate_xy)
• BOS bounds 회전: scripts/plot_bos_com_xy_sample.py:372 (rotate_box_bounds)

Axis label (앞/뒤/좌/우)

축 라벨은 “회전 후 표시 좌표 기준”으로 다음을 사용한다.

• X: X (m) [- Left / + Right]
• Y: Y (m) [+ Anterior / - Posterior]

라벨 위치: scripts/plot_bos_com_xy_sample.py:614, scripts/plot_bos_com_xy_sample.py:744

Inside / Outside 판정

프레임별로 아래 조건을 만족하면 inside로 판정한다.

• BOS_minX <= COM_X <= BOS_maxX and BOS_minY <= COM_Y <= BOS_maxY

구현 위치: scripts/plot_bos_com_xy_sample.py:313

유효 프레임(valid frame) 정의:

• COM/BOS가 NaN/Inf가 아닌 프레임
• BOS_min <= BOS_max bounds 순서가 정상인 프레임

유효 프레임 필터링 위치: scripts/plot_bos_com_xy_sample.py:300

PNG(정적) 구성

정적 PNG는 “trial 전체를 한 장”으로 요약한다.

• 모든 유효 프레임의 BOS 사각형 외곽선을 얇게 누적 오버레이(연한 회색)
• COM 전체 궤적(파랑) + inside/outside 점 분리(초록/빨강)
• 이벤트 프레임 점 마커 강조:
  • platform_onset: 검정 원
  • platform_offset: 주황 사각형
  • step_onset: 보라 삼각형 (step_onset이 null이면 생략)

GIF(애니메이션) 구성

GIF는 “프레임별로 BOS + 누적 COM + 현재 COM 상태”를 보여준다.

• BOS: 반투명 하늘색 fill + 경계선
• COM 누적 궤적: 시작~현재 프레임까지 계속 연장
• 현재 COM 점: inside=초록, outside=빨강
• 좌상단 패널: frame/time/status/event/bos 상태 및 inside ratio

Step trial에서 BOS freeze (step_onset 이후)

요구사항: step이면 BOS는 step_onset에서 멈추고(COM은 끝까지 계속) nonstep은 예외로 BOS가 계속 갱신.

• step_onset_local이 존재하면(step trial로 간주) step_onset 시점의 BOS bounds를 찾아 그 이후 프레임에서 고정한다.
• step_onset_local이 null이면(nonstep) BOS는 매 프레임 갱신된다.

구현 위치: scripts/plot_bos_com_xy_sample.py:653

출력 파일 규칙

기본 출력 경로:

• output/figures/bos_com_xy_sample/

파일명:

• <subject>__velocity-<v>__trial-<n>__bos_com_xy_static.png
• <subject>__velocity-<v>__trial-<n>__bos_com_xy_anim.gif

suffix는 --png_name_suffix, --gif_name_suffix로 바꿀 수 있다.

“오른발(step_R)만” trial 찾는 방법

이 스크립트는 trial을 자동으로 step_R만 골라주진 않는다. (trial state는 “표시용”)

빠른 방법(추천): data/perturb_inform.xlsm의 platform 시트에서

• subject == <이름>
• state == step_R

인 행을 찾아 velocity/trial을 그대로 CLI에 넣는다.

터미널에서 빠르게 조회(예시):

conda run -n module python -c \"import pandas as pd; df=pd.read_excel('data/perturb_inform.xlsm', sheet_name='platform'); df=df[['subject','velocity','trial','state']]; print(df[(df['subject'].astype(str).str.strip()=='조민석') & (df['state'].astype(str).str.strip()=='step_R')].sort_values(['velocity','trial']).to_string(index=False))\"

재현성/검증(권장)

1) 생성 확인

• PNG/GIF 파일 존재 확인
• 콘솔에 trial 선택/valid 통계/inside 비율/저장 경로 로그가 나오는지 확인

2) MD5 재현성 확인(동일 인자 2회 실행)

md5sum output/figures/bos_com_xy_sample/*.png output/figures/bos_com_xy_sample/*.gif | sort

같은 명령을 동일 인자로 다시 실행했을 때 MD5가 변하면 비결정성 원인이 있는지 확인한다.

자주 나는 문제와 대응

• Missing required columns: ...
  • 원인: 입력 CSV가 기대 컬럼을 포함하지 않음.
  • 대응: output/all_trials_timeseries.csv를 생성하는 upstream pipeline을 먼저 점검.
• Event workbook not found: ...
  • 원인: data/perturb_inform.xlsm 경로가 다름.
  • 대응: --event_xlsm로 올바른 xlsm 경로 지정, 또는 --no-show_trial_state로 상태표시를 끄고 진행.
• No valid frame remains ...
  • 원인: COM/BOS가 전부 NaN이거나 BOS bounds가 전부 뒤집힘(min>max).
  • 대응: 입력 생성 단계(BOS/COM 계산)부터 확인 필요.

더 깊은 설계/코드 포인터

상세 설계/코드 포인터는 references/bos-com-xy-gif-design.md를 참고한다.