first commit

This commit is contained in:
김민성
2025-07-16 17:33:20 +09:00
commit 4b9161db45
51 changed files with 23478 additions and 0 deletions

484
docs/developer_guide.md Normal file
View File

@@ -0,0 +1,484 @@
# 개발자 가이드
PDF 도면 분석기의 개발 및 확장을 위한 가이드입니다.
## 목차
1. [프로젝트 구조](#프로젝트-구조)
2. [개발 환경 설정](#개발-환경-설정)
3. [모듈 구조](#모듈-구조)
4. [API 참조](#api-참조)
5. [확장 가이드](#확장-가이드)
6. [기여하기](#기여하기)
## 프로젝트 구조
```
fletimageanalysis/
├── main.py # 메인 애플리케이션 진입점
├── config.py # 설정 관리 모듈
├── pdf_processor.py # PDF 처리 및 이미지 변환
├── gemini_analyzer.py # Gemini API 연동
├── ui_components.py # UI 컴포넌트 정의
├── utils.py # 유틸리티 함수들
├── setup.py # 설치 스크립트
├── test_project.py # 테스트 스크립트
├── requirements.txt # Python 의존성
├── .env.example # 환경 변수 템플릿
├── README.md # 프로젝트 개요
├── LICENSE # 라이선스
├── project_plan.md # 프로젝트 계획
├── uploads/ # 업로드된 파일 저장
├── results/ # 분석 결과 저장
├── assets/ # 정적 자산
└── docs/ # 문서
├── user_guide.md # 사용자 가이드
└── developer_guide.md # 개발자 가이드
```
## 개발 환경 설정
### 필수 요구사항
- Python 3.9+
- pip 최신 버전
- Google Gemini API 키
### 개발 환경 구성
1. **저장소 클론**
```bash
git clone <repository-url>
cd fletimageanalysis
```
2. **가상 환경 생성**
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows
```
3. **개발 의존성 설치**
```bash
pip install -r requirements.txt
pip install black flake8 pytest # 개발 도구
```
4. **환경 설정**
```bash
cp .env.example .env
# .env 파일에서 GEMINI_API_KEY 설정
```
### 코드 스타일
프로젝트는 다음 코딩 스타일을 따릅니다:
- **포맷터**: Black
- **린터**: Flake8
- **라인 길이**: 88자
- **문서화**: Google 스타일 docstring
```bash
# 코드 포맷팅
black .
# 코드 검사
flake8 .
# 테스트 실행
python test_project.py
```
## 모듈 구조
### 1. config.py - 설정 관리
```python
class Config:
"""애플리케이션 설정 클래스"""
# 기본 설정
APP_TITLE = "PDF 도면 분석기"
APP_VERSION = "1.0.0"
# API 설정
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
GEMINI_MODEL = "gemini-2.5-flash"
# 파일 설정
MAX_FILE_SIZE_MB = 50
ALLOWED_EXTENSIONS = ["pdf"]
```
**주요 기능:**
- 환경 변수 로드
- 설정 유효성 검사
- 경로 관리
### 2. pdf_processor.py - PDF 처리
```python
class PDFProcessor:
"""PDF 파일 처리 클래스"""
def validate_pdf_file(self, file_path: str) -> bool:
"""PDF 파일 유효성 검사"""
def convert_pdf_page_to_image(self, file_path: str, page_number: int) -> Image:
"""PDF 페이지를 PIL Image로 변환"""
def pdf_page_to_base64(self, file_path: str, page_number: int) -> str:
"""PDF 페이지를 base64 문자열로 변환"""
```
**주요 기능:**
- PDF 파일 검증
- 페이지별 이미지 변환
- Base64 인코딩
- 메타데이터 추출
### 3. gemini_analyzer.py - API 연동
```python
class GeminiAnalyzer:
"""Gemini API 이미지 분석 클래스"""
def analyze_image_from_base64(self, base64_data: str, prompt: str) -> str:
"""Base64 이미지 데이터 분석"""
def analyze_pdf_images(self, base64_images: list, prompt: str) -> dict:
"""여러 PDF 페이지 일괄 분석"""
```
**주요 기능:**
- API 클라이언트 관리
- 이미지 분석 요청
- 응답 처리
- 오류 처리
### 4. ui_components.py - UI 컴포넌트
```python
class UIComponents:
"""UI 컴포넌트 클래스"""
@staticmethod
def create_app_bar() -> ft.AppBar:
"""애플리케이션 상단 바 생성"""
@staticmethod
def create_file_upload_section() -> ft.Container:
"""파일 업로드 섹션 생성"""
```
**주요 기능:**
- 재사용 가능한 UI 컴포넌트
- Material Design 스타일
- 이벤트 핸들러 정의
### 5. utils.py - 유틸리티
```python
class FileUtils:
"""파일 관련 유틸리티"""
class AnalysisResultSaver:
"""분석 결과 저장"""
class DateTimeUtils:
"""날짜/시간 유틸리티"""
```
**주요 기능:**
- 파일 조작
- 결과 저장
- 텍스트 처리
- 검증 함수
## API 참조
### PDFProcessor
#### `validate_pdf_file(file_path: str) -> bool`
PDF 파일의 유효성을 검사합니다.
**매개변수:**
- `file_path`: PDF 파일 경로
**반환값:**
- `bool`: 유효한 PDF인지 여부
#### `get_pdf_info(file_path: str) -> dict`
PDF 파일의 메타데이터를 조회합니다.
**반환값:**
```python
{
'page_count': int,
'metadata': dict,
'file_size': int,
'filename': str
}
```
### GeminiAnalyzer
#### `analyze_image_from_base64(base64_data: str, prompt: str) -> str`
Base64 이미지를 분석합니다.
**매개변수:**
- `base64_data`: Base64로 인코딩된 이미지
- `prompt`: 분석 요청 텍스트
**반환값:**
- `str`: 분석 결과 텍스트
### AnalysisResultSaver
#### `save_analysis_results(pdf_filename, analysis_results, pdf_info, analysis_settings) -> str`
분석 결과를 텍스트 파일로 저장합니다.
**반환값:**
- `str`: 저장된 파일 경로
## 확장 가이드
### 새로운 분석 모드 추가
1. **UI 업데이트**
```python
# ui_components.py에서 새 라디오 버튼 추가
ft.Radio(value="new_mode", label="새로운 모드")
```
2. **분석 로직 추가**
```python
# main.py의 run_analysis()에서 프롬프트 설정
elif self.analysis_mode.value == "new_mode":
prompt = "새로운 분석 모드의 프롬프트"
```
### 새로운 파일 형식 지원
1. **설정 업데이트**
```python
# config.py
ALLOWED_EXTENSIONS = ["pdf", "docx"] # 새 형식 추가
```
2. **처리기 확장**
```python
# 새로운 처리 클래스 구현
class DOCXProcessor:
def validate_docx_file(self, file_path: str) -> bool:
# DOCX 검증 로직
pass
```
### 새로운 AI 모델 지원
1. **설정 추가**
```python
# config.py
ALTERNATIVE_MODEL = "claude-3-5-sonnet"
```
2. **분석기 확장**
```python
class ClaudeAnalyzer:
def analyze_image(self, image_data: str) -> str:
# Claude API 연동 로직
pass
```
### UI 컴포넌트 확장
1. **새 컴포넌트 추가**
```python
# ui_components.py
@staticmethod
def create_advanced_settings_section() -> ft.Container:
"""고급 설정 섹션"""
return ft.Container(...)
```
2. **메인 UI에 통합**
```python
# main.py의 build_ui()에서 새 컴포넌트 추가
```
## 기여하기
### 기여 프로세스
1. **이슈 생성**
- 새 기능이나 버그 리포트
- 명확한 설명과 예시 제공
2. **브랜치 생성**
```bash
git checkout -b feature/new-feature
git checkout -b bugfix/fix-issue
```
3. **개발 및 테스트**
```bash
# 개발 후 테스트 실행
python test_project.py
black .
flake8 .
```
4. **커밋 및 푸시**
```bash
git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature
```
5. **Pull Request 생성**
- 명확한 제목과 설명
- 변경사항 설명
- 테스트 결과 포함
### 커밋 메시지 규칙
- `feat:` 새로운 기능
- `fix:` 버그 수정
- `docs:` 문서 업데이트
- `style:` 코드 스타일 변경
- `refactor:` 코드 리팩토링
- `test:` 테스트 추가/수정
- `chore:` 기타 작업
### 코드 리뷰 체크리스트
- [ ] 코드 스타일 준수 (Black, Flake8)
- [ ] 테스트 통과
- [ ] 문서화 완료
- [ ] 타입 힌트 추가
- [ ] 에러 처리 적절
- [ ] 성능 고려
- [ ] 보안 검토
## 디버깅
### 로깅 설정
```python
import logging
# 개발 시 상세 로깅
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```
### 일반적인 디버깅 시나리오
1. **API 연결 문제**
```python
# gemini_analyzer.py에서 연결 테스트
if not analyzer.validate_api_connection():
logger.error("API 연결 실패")
```
2. **파일 처리 오류**
```python
# pdf_processor.py에서 상세 오류 정보
try:
doc = fitz.open(file_path)
except Exception as e:
logger.error(f"PDF 열기 실패: {e}")
```
3. **UI 업데이트 문제**
```python
# main.py에서 스레드 안전 업데이트
def safe_ui_update():
def update():
# UI 업데이트 코드
self.page.update()
self.page.run_thread(update)
```
## 성능 최적화
### 메모리 관리
1. **대용량 PDF 처리**
```python
# 페이지별 순차 처리
for page_num in range(total_pages):
# 메모리 해제
del previous_image
gc.collect()
```
2. **이미지 크기 최적화**
```python
# 적절한 줌 레벨 선택
zoom = min(2.0, target_width / pdf_width)
```
### API 호출 최적화
1. **요청 배치 처리**
```python
# 여러 페이지를 하나의 요청으로 처리
combined_prompt = f"다음 {len(images)}개 이미지를 분석..."
```
2. **캐싱 구현**
```python
# 분석 결과 캐시
@lru_cache(maxsize=100)
def cached_analysis(image_hash: str, prompt: str) -> str:
return analyzer.analyze_image(image_data, prompt)
```
---
더 자세한 정보나 질문이 있으시면 GitHub Issues에서 문의해 주세요.

222
docs/user_guide.md Normal file
View File

@@ -0,0 +1,222 @@
# 사용자 가이드
PDF 도면 분석기의 상세한 사용법을 안내합니다.
## 목차
1. [설치 후 첫 실행](#설치-후-첫-실행)
2. [기본 사용법](#기본-사용법)
3. [고급 기능](#고급-기능)
4. [문제 해결](#문제-해결)
5. [팁과 요령](#팁과-요령)
## 설치 후 첫 실행
### 1. API 키 설정 확인
애플리케이션을 처음 실행하기 전에 Gemini API 키가 올바르게 설정되었는지 확인하세요.
```bash
# .env 파일 확인
GEMINI_API_KEY=your_actual_api_key_here
```
### 2. 테스트 실행
설치가 올바르게 되었는지 확인:
```bash
python test_project.py
```
### 3. 애플리케이션 실행
```bash
python main.py
```
## 기본 사용법
### 1. PDF 파일 업로드
1. **파일 선택**: "PDF 파일 선택" 버튼을 클릭합니다.
2. **파일 확인**: 선택된 파일의 정보(이름, 페이지 수, 크기)를 확인합니다.
3. **유효성 검사**: 시스템이 자동으로 PDF 파일의 유효성을 검사합니다.
**지원되는 파일:**
- ✅ PDF 형식 파일
- ✅ 최대 50MB 크기
- ✅ 모든 페이지 수
**지원되지 않는 파일:**
- ❌ 암호로 보호된 PDF
- ❌ 손상된 PDF 파일
- ❌ 이미지 파일 (JPG, PNG 등)
### 2. 분석 설정
#### 페이지 선택
- **첫 번째 페이지**: 첫 페이지만 분석 (빠름, 비용 절약)
- **모든 페이지**: 전체 페이지 분석 (상세함, 시간 소요)
#### 분석 모드
- **기본 분석**: 문서 유형과 기본 정보 분석
- **상세 분석**: 도면, 도표, 텍스트 등 상세 분석
- **사용자 정의**: 원하는 분석 내용을 직접 입력
### 3. 분석 실행
1. **분석 시작**: "분석 시작" 버튼을 클릭합니다.
2. **진행 상황 확인**: 진행률 바와 상태 메시지를 확인합니다.
3. **결과 확인**: 분석 완료 후 결과를 검토합니다.
### 4. 결과 저장
분석 완료 후 두 가지 형식으로 저장할 수 있습니다:
- **텍스트 저장**: 읽기 쉬운 텍스트 형식
- **JSON 저장**: 구조화된 데이터 형식
## 고급 기능
### 사용자 정의 분석
분석 모드에서 "사용자 정의"를 선택하면 원하는 분석 내용을 직접 지정할 수 있습니다.
**예시 프롬프트:**
```
이 도면에서 다음 정보를 추출해주세요:
1. 도면 제목과 도면 번호
2. 주요 치수 정보
3. 사용된 재료 정보
4. 특별한 주의사항
```
### 대용량 PDF 처리
큰 PDF 파일을 처리할 때 팁:
1. **첫 페이지만 분석**: 전체 분석 전에 테스트
2. **인터넷 연결 확인**: 안정적인 연결 필요
3. **충분한 시간 확보**: 페이지당 1-2분 소요
### 배치 처리
여러 PDF를 순차적으로 처리하는 방법:
1. 첫 번째 PDF 분석 완료
2. 결과 저장
3. 다음 PDF 업로드
4. 반복
## 문제 해결
### 일반적인 오류들
#### 1. API 키 오류
```
오류: Gemini API 키가 설정되지 않았습니다.
```
**해결책:**
- `.env` 파일의 `GEMINI_API_KEY` 확인
- API 키가 올바른지 Google AI Studio에서 확인
#### 2. PDF 파일 오류
```
오류: 유효하지 않은 PDF 파일입니다.
```
**해결책:**
- 다른 PDF 뷰어에서 파일 열어보기
- 파일 손상 여부 확인
- 파일 크기 제한 확인 (50MB 이하)
#### 3. 네트워크 오류
```
오류: 분석 중 오류가 발생했습니다.
```
**해결책:**
- 인터넷 연결 상태 확인
- 방화벽 설정 확인
- 잠시 후 다시 시도
#### 4. 메모리 부족
```
오류: 메모리가 부족합니다.
```
**해결책:**
- 다른 프로그램 종료
- 첫 번째 페이지만 분석
- 시스템 재시작
### 로그 확인
문제 발생 시 콘솔 출력을 확인하세요:
```bash
python main.py > app.log 2>&1
```
## 팁과 요령
### 1. 효율적인 분석
**빠른 분석을 위해:**
- 첫 번째 페이지만 선택
- 기본 분석 모드 사용
- 작은 크기의 PDF 사용
**정확한 분석을 위해:**
- 모든 페이지 선택
- 상세 분석 모드 사용
- 구체적인 사용자 정의 프롬프트 작성
### 2. 프롬프트 작성 요령
**좋은 프롬프트 예시:**
```
이 건축 도면을 분석하여 다음을 알려주세요:
- 건물 유형과 규모
- 주요 치수 (길이, 폭, 높이)
- 방의 개수와 용도
- 특별한 설계 요소
```
**피해야 할 프롬프트:**
```
분석해줘 (너무 일반적)
모든 것을 알려줘 (너무 광범위)
```
### 3. 결과 활용
**텍스트 결과**:
- 보고서 작성에 적합
- 직접 복사/붙여넣기 가능
**JSON 결과**:
- 다른 시스템과 연동
- 추가 데이터 처리 가능
### 4. 성능 최적화
**시스템 성능 향상:**
- 충분한 RAM 확보 (8GB 이상 권장)
- SSD 사용 시 더 빠른 처리
- 안정적인 인터넷 연결
**비용 최적화:**
- 필요한 페이지만 분석
- 기본 분석 모드 우선 사용
- 중복 분석 방지
## 자주 묻는 질문 (FAQ)
### Q: 분석 시간이 얼마나 걸리나요?
A: 페이지당 1-2분 정도 소요됩니다. 네트워크 상태와 이미지 복잡도에 따라 달라집니다.
### Q: 어떤 종류의 도면을 분석할 수 있나요?
A: 건축 도면, 기계 도면, 전기 회로도, 지도, 차트 등 모든 종류의 이미지가 포함된 PDF를 분석할 수 있습니다.
### Q: 분석 결과의 정확도는 어느 정도인가요?
A: Google Gemini AI의 최신 기술을 사용하여 높은 정확도를 제공하지만, 복잡한 도면이나 불분명한 이미지의 경우 제한이 있을 수 있습니다.
### Q: 개인정보나 민감한 문서도 안전한가요?
A: 업로드된 파일은 로컬에서만 처리되며, Google API로는 이미지 데이터만 전송됩니다. 원본 파일은 로컬에 보관됩니다.
### Q: 오프라인에서도 사용할 수 있나요?
A: 아니요. Gemini API 호출을 위해 인터넷 연결이 필요합니다.
---
추가 질문이나 문제가 있으시면 GitHub Issues에서 문의해 주세요.