기술 · 실용 가이드
이동 후 KiCad 3D 모델이 사라졌나요? 문제가 있는 부분만 바꾸세요
복사한 프로젝트와 라이브러리의 모델 참조를 목록으로 정리하고, 설정 변경과 파일 수정을 구분한 뒤, 이전 모델 폴더를 더 이상 사용하지 않기 전에 풋프린트 전체 뷰어, PCB 보기, STEP 출력을 확인하세요.
폴더 이동이나 업그레이드 후 KiCad 모델이 보이지 않는다면, 먼저 무엇을 찾지 못하는지 파악하세요. 설정된 루트 경로인지, 풋프린트에 저장된 경로인지, 모델 파일 자체인지 구분해야 합니다. 복사본에서 작업하고, 의도한 모델을 복구하는 데 필요한 가장 작은 변경을 선택하세요.
보드는 자체 풋프린트 인스턴스를 보관하므로, 라이브러리의 풋프린트를 고쳐도 이미 배치된 풋프린트가 즉시 수정되지는 않습니다. 이 보드 내 복사본은 설계 안에 실제로 내장된 3D 파일과도 다릅니다. 아래 절차는 수정 전에 이 경우들을 구분한 다음, 필요한 보기와 내보내기 결과를 확인합니다.
1. 설계를 복사하고 범위를 정하세요
KiCad를 닫고 프로젝트, 사용자 정의 풋프린트 라이브러리, 모델 폴더를 복사하세요. 이 단계에서는 원본 폴더를 그대로 유지합니다. KiCad 버전, 운영체제, 이전과 새 루트 경로, 프로젝트 위치, 관련 경로 변수 값, 다른 프로젝트가 같은 모델을 사용하는지를 기록하세요.
검사할 프로젝트와 라이브러리 복사본 폴더를 나열하세요. 라이브러리의 .kicad_mod 파일과 배치된 풋프린트를 담고 있는 .kicad_pcb 파일을 모두 포함합니다. 영향을 받는 부품은 보드의 참조 지정자, 라이브러리 풋프린트, 예상 모델 형상을 기록하세요. 이렇게 하면 모든 풋프린트에 모델이 있어야 한다고 가정하지 않고, 이후 검증에서 확인할 대상을 명확히 정할 수 있습니다.
2. 범위를 정한 후보 목록을 만드세요
POSIX 셸에서 두 복사본이 들어 있는 작업 폴더를 기준으로 아래 명령을 실행하세요. 예시 디렉터리 이름을 실제 이름으로 바꾸고, 아직 사용하지 않은 보고서 파일명을 선택합니다. 이 명령은 선택한 설계 파일을 읽고 검색 대상 폴더 밖에 보고서를 씁니다.
rg --no-config --hidden --no-ignore --json --multiline --glob '*.kicad_mod' --glob '*.kicad_pcb' '\(model\s+"' -- ./project-copy ./library-copy > ../kicad-model-matches.jsonl 2> ../kicad-model-scan-errors.txt
JSON 일치 기록과 그 안의 path, line_number, lines, submatches 필드를 읽으세요. 여러 토큰이 하나의 기록에 들어갈 수 있습니다. 각 후보 파일을 열어 모델 참조 전체를 확인하세요. JSON은 파일명에 개행 문자가 들어 있어도 파일명 경계를 보존하므로, 이 기록을 콜론으로 나누지 마세요. 이는 텍스트 검색이며, KiCad 구문 분석기나 모델 경로를 해석하는 도구는 아닙니다.
숨김 폴더와 무시 대상 폴더도 포함되며, 이 패턴은 한 줄 안이나 여러 줄에 걸친 모델 토큰을 찾을 수 있습니다. 디렉터리 심볼릭 링크는 따라가지 않으며, 바이너리 파일, 아카이브 파일, 다른 확장자의 파일은 명시한 범위 밖입니다. 다른 라이브러리 복사본의 루트가 있으면 명시적으로 추가하고 검색 오류를 검토하세요. 종료 코드 0은 일치 항목이 있음, 1은 일치 항목이 없음, 2는 오류를 뜻하며, 어느 것도 모든 참조를 검사했다는 증거는 아닙니다. ripgrep 15.2.0을 사용한 범위가 제한된 Linux 테스트에서는 의도한 합성 후보를 찾았고 입력 파일의 해시는 바뀌지 않았습니다. 이 기사를 위해 KiCad GUI 실행, 저장 후 다시 열기, STEP 내보내기를 수행하지는 않았습니다.
3. 각 참조에 필요한 변경을 선택하세요
공유 사용자 정의 변수: ${MY_3DMODELS}/Connectors/part.step에서 변수 뒤의 경로가 여전히 올바르다면 새 루트 아래의 파일을 확인하세요. 그것으로 충분하다면 Preferences → Configure Paths에서 MY_3DMODELS 값만 바꿉니다. 새 공유 루트에는 다른 변수와 구분되는 이름을 사용하고, 디렉터리의 절대 경로를 값으로 직접 지정하세요. 외부에서 정의된 변수는 우선 적용되며 여기서는 읽기 전용으로 표시되므로, 실제로 정의된 곳에서 수정해야 합니다. KIPRJMOD는 아래에서 설명하는 예외입니다.
프로젝트 상대 참조: 정상적으로 작동하는 ${KIPRJMOD}/models/part.step 참조를 유지하고 models 디렉터리를 프로젝트와 함께 옮기세요. KIPRJMOD는 프로젝트 폴더를 따르며 다른 값으로 덮어쓸 수 없습니다. 변수 없이 ../로 시작하는 경로는 영향을 받는 보기에서 실제 기준 위치를 확인해야 합니다. 기존 상대 참조가 적합하지 않을 때만 명시적인 프로젝트 루트나 공유 루트를 선택하세요.
이전 버전 변수 또는 내장 파일: KICAD6를 KICAD10으로 기계적으로 바꾸지 마세요. 먼저 명시적으로 지정된 이전 설정이 있는지, 문서에 설명된 대체 해석 동작과 실제 대상 파일은 무엇인지 확인합니다. 정상적으로 작동하는 참조는 유지하세요. 마찬가지로 유효한 kicad-embed:// 참조도 유지하고, 그 파일을 소유한 보드나 풋프린트의 해당 내장 파일 항목을 확인하세요. 이 참조는 외부 루트 교체 대상이 아닙니다.
해석되지 않는 외부 경로 또는 누락된 파일: 의도한 파일과 필요한 최소 수정을 기록하세요. 새 루트가 누락된 모델을 만들어 주거나 .wrl 참조를 실제로 존재하는 .step 파일로 바꿔 주지는 않습니다. 대체 파일을 선택하기 전에 실제 파일명, 확장자, 필요한 내보내기 형식을 확인하세요. 영향을 받는 각 참조에 대해 설정만 변경, 유지, 수정, 누락 파일 해결 중 어떤 결정을 내렸는지 목록에 남깁니다.
4. 필요한 참조만 수정하세요
잘못된 외부 경로로 확인된 경우에는 설계 복사본에서 선택한 모델 항목을 바꾸거나, 범위를 좁힌 텍스트 수정 내용을 검토하세요. 이전 루트 아래의 경로 대응 관계가 검증된 곳에서만 루트를 교체합니다. 별도의 수정이 필요한 경우가 아니라면 파일명, 확장자, 오프셋, 배율, 회전을 유지하세요. 전체 변경 내용을 비교해 무관한 변경이나 손상된 구문이 없는지 확인합니다.
해당 라이브러리 풋프린트와 영향을 받는 각 보드 인스턴스를 확인하세요. KiCad의 Compare Footprint with Library 도구로 차이를 확인할 수 있습니다. Update Footprints from Library는 더 넓은 범위를 동기화하는 작업이며, 사용자 정의된 보드 풋프린트도 바꿀 수 있으므로 그런 변경을 의도할 때만 사용하세요. 경로를 복구하는 과정에서 사용자 정의 패드, 그래픽, 다른 설계 속성이 조용히 교체되어서는 안 됩니다.
5. 다시 시작하고 세 가지 출력을 모두 확인하세요
경로 설정을 바꾼 뒤에는 KiCad를 종료하고 다시 시작하세요. 영향을 받는 각 라이브러리 풋프린트를 풋프린트 편집기의 전체 3D 뷰어(Footprint Editor 3D Viewer)에서 엽니다. 일반적으로 Alt+3을 사용합니다. Footprint Properties의 작은 미리보기는 편집 중에 유용하지만, 여기서 요구하는 전체 뷰어 확인을 대신하지는 않습니다. 그런 다음 PCB 3D Viewer에서 복사한 보드를 열고, 영향을 받는 부품의 배치, 방향, 모델 형상을 점검 목록과 비교하세요.
부품 내보내기를 활성화하고 의도한 부품 선택 및 제외 설정을 적용한 상태에서, 복사한 보드를 STEP으로 내보내세요. VRML .wrl 모델은 STEP 출력에 직접 포함되지 않습니다. Substitute similarly named models를 활성화하면 내보내기 도구가 적절한 이름의 대응 STEP 파일을 사용할 수 있습니다. VRML 미리보기가 보인다는 이유만으로 내보내기가 준비되었다고 가정하지 말고, 필요한 대응 파일이 실제로 있는지 확인하세요.
내보낸 STEP 파일을 실제로 사용할 기계 CAD 도구에서 열고, 예상 형상과 위치를 비교하세요. 풋프린트 보기, 보드 보기, 내보내기 중 어느 검증을 통과했는지 기록합니다. 특정 뷰어에서 상대 경로 문제가 보고되었다면 그 뷰어를 별도로 확인할 이유가 되지만, 모든 설치 환경에 같은 결함이 있다는 증거는 아닙니다.
6. 이전 루트가 더 이상 필요하지 않음을 입증하세요
설계 복사본이 검증을 통과하면, 이 테스트에서 이전 외부 모델 폴더에 일시적으로 접근할 수 없게 하세요. 다른 프로젝트에 지장을 주지 않을 때만 되돌릴 수 있는 이름 변경을 사용하고, 그렇지 않으면 격리된 테스트 환경을 사용합니다. KiCad를 종료하고 복사한 프로젝트를 다시 연 뒤, 후보 검색과 세 가지 출력 검증을 모두 반복하세요. 남아 있는 참조를 선택한 경로 구조와 대조합니다. 유효한 이전 버전 변수, 프로젝트 상대 경로, 내장 파일 참조는 그대로 남아 있다는 이유만으로 실패가 아닙니다.
모델이 사라지거나, 파일이 열리지 않거나, 변경 내역이 의도한 범위를 넘으면 이전 위치를 복원하고 해당 항목을 해결한 뒤 계속하세요. 다음 설계 검토가 끝날 때까지 원본 백업을 보관합니다. 다른 컴퓨터로 옮기거나 라이브러리 또는 KiCad 버전이 바뀌면 관련 검증을 반복하세요. 플러그인이 관리하는 파일, 다른 패키지 디렉터리 구조, KiCad 9–10 범위 밖의 버전은 별도로 적용 범위를 평가해야 합니다.
