==================================================
 교각 철근 프로그램 사용법 (메모장용)
==================================================

[1] 이 프로그램이 뭔가요?
  - 철근의 구부림 반지름, 갈고리 길이 같은 값을 계산하는 도구입니다.
  - 지금은 계산 모듈 1개(rebar_calc.py)와 테스트가 있습니다.
  - 앞으로 철근 수량, 간격, Rhino 배치 코드를 이 폴더에 계속 추가합니다.


[2] 폴더 위치 (전부 D 드라이브)
  프로젝트 폴더 : D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program
  계산 모듈     : D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program\scripts\rebar_calc.py
  테스트        : D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program\tests\test_rebar_calc.py
  설계 규칙     : D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program\docs\design_rules.md
  할 일 목록    : D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program\docs\tasks.md
  경로 목록     : D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program\docs\paths.md
  이 사용법     : D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program\사용법.txt

  ※ 기존 프로젝트 D:\Rhino-MCP\rhino-mcp-main 은 참고용입니다. 수정하지 마세요.


[3] 터미널(PowerShell) 여는 방법
  1) 윈도우 탐색기에서 D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program 폴더를 엽니다.
  2) 위쪽 주소창을 클릭하고 powershell 이라고 입력한 뒤 Enter.
  3) 파란 창이 열리면 이미 프로젝트 폴더 안에 있는 상태입니다.


[4] 테스트 실행 (계산이 맞는지 확인)
  터미널에서 아래를 입력하고 Enter:

      python -m pytest -q

  - 마지막 줄에 "119 passed" 라고 나오면 모두 정상입니다.
    (앞의 숫자는 테스트가 늘어나면 같이 늘어납니다. "failed" 가 없으면 정상입니다.)
  - "failed" 라고 나오면 어느 계산이 틀렸는지 표시됩니다. 그 내용을 Claude에게 붙여넣으세요.

  ※ "python" 이 안 되면 아래처럼 전체 경로로 실행하세요:

      C:\Users\User\AppData\Local\Programs\Python\Python312\python.exe -m pytest -q


[5] 계산 모듈 직접 써보기
  터미널에서 아래를 입력하면 계산기처럼 쓸 수 있습니다.

      cd scripts
      python

  파란 창에 ">>>" 가 나오면 한 줄씩 입력합니다.

      >>> import rebar_calc as rc
      >>> rc.nominal_diameter("H25")        # 공칭 직경
      25.4
      >>> round(rc.bend_radius("H25"), 1)   # 구부림 반지름 (3db)
      76.2
      >>> round(rc.bend_radius("H29"), 1)   # H29는 4db
      114.4
      >>> round(rc.bend_radius("H16", is_stirrup=True), 1)   # 스터럽 D16 이하는 2db
      31.8
      >>> round(rc.hook_extension("H25", 90), 1)    # 90도 갈고리 연장 길이 (12db)
      304.8
      >>> round(rc.hook_extension("H25", 135), 1)   # 135도는 6db
      152.4
      >>> rc.satisfies_kds_bend("H25", 76.2)   # KDS 기준을 만족하나요?
      True

  끝낼 때는 exit() 를 입력합니다.
  모든 길이의 단위는 mm 입니다.

  ※ round(값, 1) 은 소수 첫째 자리까지 반올림하는 명령입니다.
    round 없이 쓰면 76.19999999999999 처럼 아주 작은 오차가 보일 수 있습니다.
    컴퓨터가 소수를 계산하는 방식 때문이고, 값은 맞습니다.


[6] 함수 설명표
  nominal_diameter(이름)            공칭 직경 (예: "H25" -> 25.4)
  bend_radius(이름, is_stirrup)     프로젝트 적용 구부림 반지름
                                    (D10~D25 3db, D29~D35 4db, D38 이상 5db,
                                     스터럽 D16 이하 2db)
  kds_min_inner_diameter(이름)      KDS 24 14 21 최소 내면 지름
                                    (D16 이하 2db, D19 이상 3.5db)
  satisfies_kds_bend(이름, 반지름)   KDS 최소값을 만족하면 True
  hook_extension(이름, 각도)         갈고리 연장 길이 (90도 12db, 135도 6db,
                                    180도 4db 또는 60mm 중 큰 값)
  kds_min_hook_extension(이름, 각도) KDS 최소 연장 길이 (90~150도 5db)

  철근 이름은 "H25" 처럼 씁니다. "D25", 소문자 "h25" 도 됩니다.
  지원 규격: H10, H13, H16, H19, H22, H25, H29, H32, H35, H38

  --- 배치 계산 (scripts\rebar_layout.py) ---
  사용: import rebar_layout as rl
  center_out_positions(본수, 간격)         중심에서 바깥으로 놓은 폭방향 위치 목록
                                          (짝수=중심에 철근 없음, 홀수=중심에 1본)
  snapped_array(본수, 간격, 폭, 피복)       바깥 2본은 피복에 맞추고 안쪽은 중심에서 바깥으로
                                          (1CYCLE 방식. 예: 14본, 250, 3500, 120)
  min_horizontal_clear(이름, gmax)         수평 최소 순간격 max(1.5db, 1.5Gmax, 40)
  horizontal_spacing_ok(위치목록, 이름)     간격이 충분하면 True
  min_vertical_clear(이름)                 다단 연직 최소 순간격 max(25, db)
  vertical_pitch_ok(이름, 단 간격)          단 간격이 충분하면 True
  tier_elevations(상면높이, 피복, 단수, 간격)  각 단의 높이 목록
  bar_weight(이름, 길이mm, 본수)            중량(kg)
  array_summary(이름, 길이mm, 위치목록)      본수, 총길이(m), 중량(kg)

  예)  >>> import rebar_layout as rl
       >>> rl.snapped_array(14, 250, 3500, 120)
       [-1630.0, -1375.0, ..., -125.0, 125.0, ..., 1375.0, 1630.0]

  ※ 굵은골재 최대치수(gmax)는 가정값 25mm 입니다. 설계서 값이 다르면 알려주세요.
  ※ 단위중량은 H16, H19, H22, H25, H29 만 등록되어 있습니다. 다른 규격은 오류가 납니다.


  --- 좌표 변환 (scripts\frame.py) ---
  월드 좌표 (x, y, z) 를 코핑 기준 좌표 (s, t, z) 로 바꾸거나 되돌립니다.
    s = 코핑 길이방향, t = 폭방향, z = 높이(그대로)
  원점과 각도는 언제든 바꿀 수 있습니다. (값으로 받기 때문입니다)

  사용: import frame as fr
  fr.Frame(원점x, 원점y, 각도)            프레임 직접 만들기 (각도는 라디안)
  fr.from_two_points((x1,y1), (x2,y2))   두 점으로 만들기 (원점=가운데, s축=1번->2번 방향)
                                         예: 2주식 교각의 두 기둥 중심
  f.to_local(x, y, z)                    월드 -> 로컬
  f.to_world(s, t, z)                    로컬 -> 월드
  fr.convert(점, 프레임1, 프레임2)         프레임1 기준 값을 프레임2 기준 값으로

  예)  >>> import frame as fr
       >>> f = fr.from_two_points((480708784, 153831202), (480721068, 153835457))
       >>> f.to_local(480708784, 153831202, 7738)
       (-6500.032326842691, -2.2737367544323206e-13, 7738)
       <- 기둥 중심: 코핑 중앙에서 s 방향으로 약 -6500, t는 0 (e-13 은 0에 아주 가까운 계산 오차)

  원점이나 각도를 바꾸고 싶으면 새 프레임을 만들어 쓰면 됩니다.
  월드 위치는 변하지 않고 로컬 숫자만 달라집니다.


  --- 철근 중심선 꺾임점 (scripts\centerline.py) ---
  단면 외곽선을 안쪽으로 피복만큼 옮긴 직선들의 교점으로 철근 중심선을 구합니다.
  2D 좌표는 (s, z) 입니다. (s=길이방향, z=높이)

  사용: import centerline as cl
  cl.centerline_points(선분목록, 피복, "left"/"right", start_len=, end_len=)
       선분목록 : 철근이 지나가는 순서와 방향대로 [(시작점, 끝점), ...]
       "left"/"right" : 콘크리트 안쪽이 진행 방향의 왼쪽인지 오른쪽인지
       start_len / end_len : 도면에 정해진 시작·끝 연장 길이 (없으면 생략)
  cl.segment_lengths(점목록)    각 구간 길이 (도면의 a, b, c, d 와 비교)
  cl.polyline_length(점목록)    전체 길이
  cl.turn_angles(점목록)        꺾임 각도(도)

  예) 대호지교 P1 형식 VII (C8/C10), 도면과 같은 값이 나옵니다:
       >>> import centerline as cl
       >>> segs = [((12100,10738),(12100,9238)), ((12100,9238),(8100,7738)),
       ...         ((8100,7738),(4900,7738)), ((4900,7738),(3400,8238))]
       >>> pts = cl.centerline_points(segs, 120, "right", start_len=630, end_len=2331)
       >>> [round(x, 1) for x in cl.segment_lengths(pts)]
       [630.0, 4167.1, 3158.8, 2331.0]       <- 도면 a, b, c, d

  ※ 길이는 중심선 길이입니다. 재료표의 전개길이(꺾임 보정 포함)와는 다를 수 있습니다.


  --- 철근 간섭 검사 (scripts\clash.py) ---
  철근 중심선을 선분으로 쪼개서 서로 겹치는(간섭) 철근을 찾습니다.
  간섭 = 두 철근 반지름의 합 - 중심선 최단거리 가 0.5mm 보다 클 때.
  같은 철근이나 같은 그룹(겹침이음인 뚜껑+바닥 조각)끼리는 검사하지 않습니다.

  사용: import clash as ck
  ck.Seg(시작점, 끝점, 반지름, 철근번호, 그룹번호, 마크이름)   선분 하나 만들기
  ck.find_clashes(선분목록, min_penetration=0.5)             간섭 목록 (깊은 것부터)
  ck.summarize_by_mark(간섭목록)                              마크 쌍별 개수와 최대 관입
  ck.segment_distance(p1, q1, p2, q2)                        선분 두 개 사이 최단거리

  예)  >>> import clash as ck
       >>> a = ck.Seg((-100,0,0), (100,0,0), 12.7, 1, 1, "C1")
       >>> b = ck.Seg((0,-100,20), (0,100,20), 12.7, 2, 2, "C8")
       >>> ck.find_clashes([a, b])
       [{'bar_a': 1, 'bar_b': 2, 'mark_a': 'C1', 'mark_b': 'C8',
         'penetration': 5.4, 'point': (0.0, 0.0, 10.0)}]
       <- 철근 중심이 20mm 떨어졌는데 반지름 합이 25.4 라서 5.4mm 겹침
          (실제 출력은 5.399999999999999 처럼 미세한 오차가 보일 수 있습니다)

  ※ 월드 좌표(약 4.8억)보다 frame.py 로 바꾼 로컬 좌표를 쓰면 계산이 더 정확합니다.


[7] Claude와 같이 작업하는 순서
  1) Claude에게 할 일을 말합니다. (docs\tasks.md 의 번호로 말하면 쉽습니다. 예: "T-003 시작해줘")
  2) Claude가 테스트를 먼저 만들고, 실패하는 것을 확인한 뒤 코드를 만듭니다.
  3) 끝나면 Claude가 docs 와 README 를 업데이트할지 묻습니다.
  4) 커밋(저장 기록)은 Claude가 물어본 뒤 "응" 이라고 하면 합니다.
  5) Claude는 매번 응답 끝에 "이번에 쓴 경로"를 알려줍니다.


[8] 헷갈릴 때
  - 경로가 헷갈리면 D:\★Pier 자료\pier_v1\Pier_T_rebar\Code\pier-program\docs\paths.md 를 보세요.
  - 새 프로그램은 pier-program, 옛날 자료는 rhino-mcp-main 입니다.
  - 큰 파일(렌더링, 백업, DXF, Rhino 파일)은 항상 D 드라이브에 저장합니다.