Release notes

`2.3.5`

2025/07/17
[버그 수정]
- analyze 수행시, label과 prediction의 mask 사이즈가 다르게 나오는 이슈를 해결하였습니다.
  - 이미지 사이즈가 설정한 "inspection size보다는 작지만", "inspection size에 round 처리가 된 model inspection size보다 큰 경우"에만 발생하던 이슈였습니다.
- 참고: VISIONPRD-2620

`2.3.4`

2025/06/09
SaigeToolkit 버전 업데이트: 2.6.6
[라이브러리 업데이트]
- random_erasing augmentation preview api 추가 사항 반영.
[기능 추가]
- perspective_transform과 random_erasing augmentation 추가.
  - 참고사항: [250529] 영상데이터 대응건 논의

`2.3.3`

2025/04/25
[기능 개선]
- 학습 데이터 처리 프로세스의 속도/메모리 개선
  - label 정보 전처리를 미리 수행하고 결과를 로드만 하는 방식으로 속도 개선
    - 단일 프로세스의 데이터 처리 속도 10~20% 개선.
  - 전처리된 정보를 zstandard 방식으로 압축해두어 메모리 효율 개선
    - raw 데이터를 전처리하는 대신, 압축된 정보에 대한 decompress만 수행.
  - polygon 뿐만 아니라 전체 라벨 정보를 disk에 캐싱하도록 변경
    - cache_directory로 디스크 캐싱할 경우, 라벨 데이터가 증가하더라도 RAM 메모리가 추가로 소모되지 않음.

`2.3.2`

2025/04/21
[기능 추가]
- compute_iou_from_confusion_matrix
  - mean_IoU의 한계를 보완하기 위해 overall_IoU 지표를 추가했습니다.
    - 특정 클래스가 validation에 존재하지 않을 경우 IoU 값이 0으로 계산되어 mean_IoU가 과소평가되는 문제입니다.

`2.3.1`

2025/04/17
[버그 수정]
- validation이 설정되지 않으면, model의 feature extractor가 정상 학습되지 않던 문제를 해결했습니다.
  - feature extractor가 eval mode로 되어서 batchnorm이 정상 작동하지 않던 문제입니다.
  - v1_standard, v1_deep, v2_fast, v2_standard, v2_accurate 에 해당하던 문제입니다.

`2.3.0`

2025/04/11
SaigeToolkit 버전 업데이트: 2.6.2
[라이브러리 업데이트]
- SaigeToolkit 버전 업데이트로, pytorch==2.7.0+cu128 업데이트 되었습니다.
[문서 수정]
- api docs가 수정되었습니다.
  - score에 대한 설명을 수정.
  - precision == prediction IoA, recall == label IoA 설명 추가.

`2.2.7`

2025/03/26
SaigeToolkit 버전 업데이트: 2.5.1
[기능 개선]
- AnalysisHandler를 통한 analyze()에 동시성 프로그래밍 적용.

`2.2.6`

2025/03/25
[버그 수정]
- dataloader에서 subprocess pid가 출력되지 않는 현상 수정.

`2.2.5`

2025/03/20
[버그 수정]
- Blind 영역에 예측이 발생하는 문제 해결.

`2.2.4`

2025/03/13
[버그 수정]
- version 2.2.2 업데이트로 인해 validation시 augmentation이 적용되던 버그를 수정.

`2.2.3`

2025/03/12
[버그 수정]
- ROI 설정 시, ROI 경계에 예측이 발생하던 문제 해결.
  - 내부 로직 변경: circular padding에서 reflection padding으로 변경.

`2.2.2`

2025/03/06
[버그 수정]
- SaigeToolkit==2.4.2 환경에서, Trainer.build num_workers>0이고, validation_images에 None이나 빈 리스트가 들어오는 경우 DataLoaderWorkerInitializationError가 발생하던 버그 수정.

`2.2.1`

2025/02/05
SaigeToolkit 버전 업데이트: 2.4.0
[기능 추가]
- MemorySafeDataLoader
  - 1 이상의 num_worker를 설정하여 sub-process가 생성될 때, cpu memory가 부족한 등의 문제가 발생할 경우, error message 출력하는 기능입니다.
  - CpuLowMemoryError, DataLoaderWorkerInitializationError

`2.2.0`

2025/01/15
SaigeToolkit 버전 업데이트: 2.3.1
[문서 수정]
- SaigeToolkit 의 설치 방법이 바뀌었음.
  - pip install version constraints
[기능 변경]
- Trainer 빌드 config의 resize_factor의 데이터 타입이 [float, None]에서 float으로 변경되었습니다. 기본값은 1.0 입니다.
[기능 추가]
- ClassBalancedInfiniteRandomSampler
  - 내부 연구용 클래스로 클래스 불균형이 심할 때 균일하게 데이터를 로드하기 위한 기능입니다.
[Note]
- MemorySafeDataLoader는 다음 버전에서 반영될 예정입니다.

`2.1.4`

2024/12/05
[Bug Fix]
- oversized_image_handling을 "do_not_inspect"로 설정해도 inspection_size_wh보다 큰 이미지가 정상 검사 되던 버그 수정. (2.0.34이후 버전부터 발생하던 버그)
- epoch 계산 버그 수정.
- 모델 하위호환성 이슈를 해결했습니다.
  - 2.0.34 이상의 버전에서 학습한 모델을 2.0.33 이하의 버전에서 로드시, 에러 발생.
  - 2.1.4 버전 부터는 학습한 모델을 하위 버전에서 문제 없이 로드 가능합니다.

`2.1.3`

2024/11/19
[Hotfix]
- inspection_size_wh의 list[int] 타입 추가로 인해 발생한 TypeError 수정

`2.1.2`

2024/11/15
- inspection_size_wh의 타입을 tuple[int]에서 tuple[int, int] 및 list[int]로 변경. 해당 내용 docs에 반영
- device 세팅에서 torch.device 타입이 누락된 부분 수정

`2.1.1`

2024/10/10
SaigeToolkit 버전 업데이트: 2.2.5
- revert traceback encryption
- segment label이 이미지를 벗어나는 케이스 에러 코드 추가

`2.1.0`

2024/09/26
SaigeToolkit 버전 업데이트: 2.2.3 (segment class index 에러 추가)
[minor 버전 정식 배포]
- 2.1.0

`2.1.0-rc4`

2024/09/10
SaigeToolkit 버전 업데이트: 2.2.2
[라이브러리 업데이트]
- SaigeToolkit 버전 업데이트로, python==3.11 & pytorch==2.3.0 업데이트 되었습니다.

`2.1.2-rc0 (2.1.0-rc3)`

2024/09/05
2.0.34의 변경 사항 반영
SaigeToolkit 버전 업데이트: 2.1.2

`2.1.0-rc2`

2024/08/20
2.0.32, 2.0.33의 변경사항 반영

`2.1.0-rc1`

2024/08/13
SaigeToolkit 버전 업데이트: 2.1.0
[기능 변경]
- error message를 api output에서 직접 출력하도록 수정했습니다.
  - error_code, error_message, result = api()
- VISIONPRD-1029 이슈 및 Development guide 문서의 SaigeError 정의 섹션을 참고해 주세요.
[기능 개선]
- error message에 추가적인 message 를 argument 로 입력할수 있도록 개선했습니다.
- image_load 시 발생하는 에러에 대한 messaging을 개선했습니다.

`2.1.0-rc0`

2024/08/01
SaigeToolkit 버전 업데이트: 2.0.1
[기능 개선]
- lazy import 도입
  - 실제 모듈들이 사용되기 전까지 세부 파일들을 import하지 않음.

`2.0.34`

2024/09.02
SaigeToolkit 버전 업데이트: f09f8087 (Transform 업데이트)
[기능 개선]
- 검사 이미지가 inspection size 보다 작을 경우, round resize는 skip하고 padding을 진행하게 변경.
- 위의 변경사항으로 인하여, resize_factor가 1이고 검사 이미지가 insepction size보다 작을 경우에 검사 속도가 향상되었습니다.
- padding 방법을 circular padding으로 변경.
- 참고: VISIONPRD-1101

`2.0.33`

2024.08/06
SaigeToolkit 버전 업데이트: 1dd5da0a (object contour 스케일 로직 변경)
[Bug Fix]
- num_workers > 0 인 상태에서 학습 데이터셋에 truncated image가 포함되어 있을 경우, 에러 메시지가 출력되지 않고 학습이 멈추는 에러 해결.
- 참고: VISIONPRD-1067
- 검사 결과로 나오는 heatmap과 contour의 위치가 다른 에러 해결.
- 참고: VISIONPRD-873

`2.0.32`

2024/07/30
[Hotfix]
- 다음 기능에 대한 추가 수정 사항 InferenceHandler 빌드 시에, object correctness threshold 파라미터 추가 반영 [VISIONPRD-780]

`2.0.31`

2024/07/12
SaigeToolkit 버전 업데이트: 2a00aeb5 (Image truncated error 추가)
[기능 추가]
- AnalysisHandler와 SummaryHandler build 시에, object correctness threshold를 설정할 수 있게 기능 추가.
- 참고: VISIONPRD-780
[기능 개선]
- Truncated 이미지가 데이터셋에 포함되어 있을 때 적절한 에러 메시지를 출력하도록 수정
- 참고: VISIONPRD-652

`2.0.30`

2024/06/05
[기능 추가]
- 내부 사용 API 추가 (UDDD에서 사용)

`2.0.29`

2024/05/28
SaigeToolkit 버전 업데이트: 09cefc50
[기능 개선]
- 학습 중 loss 값에 NaN이 포함되어 있는 경우 NanLossError를 발생시키도록 변경.
- CUDA device init 과정에서 발생하는 에러를 Trainer.build()에서 확인하도록 변경.

`2.0.28`

2024/04/22
[Bug Fix]
- validation에서 crop_into_tiles 옵션 선택 시 AMP로 인해 accurate 모델에서 에러가 발생하는 문제 해결.

`2.0.27`

2024/03/15
[Bug Fix]
- validation oversized 이미지 처리 방법 중, resize_to_fit 옵션 사용 시 발생하는 에러 해결.

`2.0.26`

2024/03/14
[기능 추가]
- Trainer.build에 oversized_image_hanlding 파라미터 추가: validation에서 oversized 이미지 처리 방법 설정.

`2.0.25`

2024/03/08
SaigeToolkit 버전 업데이트: c0361acf
[Bug Fix]
- ROI 설정시 inference가 되지 않는 문제 해결.

`2.0.24`

2024/01/29
SaigeToolkit 버전 업데이트: 58954162
[기능 개선]
- ROI 설정시 큰 이미지에서 processing 시간이 과도하게 걸리는 문제 해결. (PatchCropDataset logic으로 인해, 코드 최적화 부분만 적용되고 blind mask 순서 변경은 적용되지 않았습니다.)
[기능 추가]
- setup시 pretrained weight를 다운로드 하지 않고, build 폴더로 저장하지 않는 --without-pretrained-model 옵션 추가.

`2.0.23`

2024/01/11
SaigeToolkit 버전 업데이트: 70262443
[Bug Fix]
- validation image가 0개인 경우 발생하는 에러 해결.
- 매우 큰 이미지를 사용할 경우 발생하는 에러 해결.
[기능 변경]
- checkpoint의 metadata영역이 1MB -> 12MB로 확장.

`2.0.22`

2023/12/27
SaigeToolkit 버전 업데이트: 12b57553

`2.0.21`

2023/12/22
[Bug Fix]
- Summary.summarize_analysis에서 object/class_{idx}_num_predictions과 object/class_{idx}_num_labels의 idx가 잘못된 이슈 해결.

`2.0.20`

2023/12/21
SaigeToolkit 버전 업데이트: 6a4979f0
[기능 추가]
- Summary.summarize_analysis에 리턴 추가.
  - object/class_{idx}_num_predictions: 클래스를 idx로 예측한 object의 개수
  - object/class_{idx}_num_labels: 클래스가 idx인 라벨 object의 개수
[기능 개선]
- 학습 속도 및 성능 개선.
  - AMP 추가
  - DataLoader 개선
  - V1 preprocessing logic 사용
- checkpoint 저장 용량 감소.

`2.0.19`

2023/11/08
SaigeToolkit 버전 업데이트: ef3ac155
[기능 변경]
- Inference.analyze의 중간결과를 zstandard library로 압축하여 저장/로드하도록 변경 (기존에 pickle로 저장되었던 파일은 호환됨)

`2.0.18`

2023/09/08
[Bug Fix]
- v2 fast, v2 standard 모델 사용시 prediction이 왼쪽 위로 쏠리는 이슈 해결

`2.0.17`

2023/08/24
[기능 추가]
- Trainer.build() 에 cache_directory 파라미터 추가: 전처리된 학습 데이터를 해당 디렉토리에 저장해 학습 속도 향상.
- None으로 입력 시 해당 데이터를 메모리에 올려두고 사용.

`2.0.16`

2023/08/17
[기능 변경]
- 모든 데이터에 라벨 및 예측이 전혀 존재하지 않는 경우 Overall Mean IOU도 -1.0 으로 리턴

`2.0.15`

2023/08/17
[기능 변경]
- 클래스들의 평균 IOU 계산 시 모든 클래스가 아닌 라벨 혹은 예측이 존재하는 클래스들에 대해서만 평균 계산
- 라벨 혹은 예측이 존재하지 않는 클래스에 대해서는 -1.0 (음수) 리턴

`2.0.14`

2023/08/14
SaigeToolkit 버전 업데이트: e7f1e0
- [Bug Fix]
  - Windows에서 torch save 시 한글 경로가 있으면 에러가 발생하는 이슈 해결

`2.0.13`

2023/08/07
SaigeToolkit 버전 업데이트: a6a939
[Bug Fix]
- Windows에서 0번 이외의 GPU 사용 시 속도 저하 및 메모리 이슈 해결

`2.0.12`

2023/08/03
[기타]
- 배포되는 소스 파일 이름에서 딥러닝 모델 이름 제거

`2.0.11`

2023/07/31
SaigeToolkit 버전 업데이트: 7989cc
- timer관련 버그 해결: 사용하지 않는 gpu에 메모리 올리는 버그, batch_size가 1보다 큰 경우 음수 나오는 버그

`2.0.10`

2023/07/12
SaigeToolkit 버전 업데이트: ac99d5
[기능 개선]
- Trainer에서 validation을 사용하지 않는 경우 validation용 GPU 메모리를 점유하지 않도록 변경

`2.0.9`

2023/06/26
SaigeToolkit 버전 업데이트: d11caf
[기능 변경]
- Augmentation Preview API 리턴 형식 변경: (error_code, augmented_image) → (error_code, (augmented_image, augmentation_parameters))
[기능 추가]
- 체크포인트 로드 관련 에러 핸들링 추가
  - checkpoint_path에 파일이 존재하지 않으면 ModelFileNotFoundError 에러 레이즈
  - checkpoint_path의 파일이 모델 파일이 아니면 InvalidModelFileError 에러 레이즈
[기능 개선]
- Augmentation에서 saturation 내부 연산 변경: SaigeVision V1의 알고리즘을 적용해 흑백 이미지에서 발생하는 색상 이슈 해결
- Checkpoint, metadata 경로 및 파일 유효성 관련 에러 핸들링 추가
- Postprocess 퍼포먼스 최적화를 통해 속도 개선: notion 참고

`2.0.8`

2023/05/09
[기능 추가]
- Anaylsis API: 모델 빌드 없이 analysis postprocess & summary 수행
[기능 변경]
- Inference.analyze의 인풋 파라미터에서 use_saved_file 삭제: 해당 기능은 Anaylsis.analyze로 분리됨.
- Inference에서 summarize_analysis api 삭제: 해당 기능은 Summary.summarize_analysis로 분리됨.
[기능 개선]
- Trainer.to_device() 호출 시 CPU로 보내는 경우 torch.cuda.empty_cache() 호출해 GPU 메모리 일부 해제

`2.0.7`

2023/04/26
[기능 변경]
- inference_options 중 background class의 threshold는 변경 불가하게 수정
- inference_options 중 params.object_boundary_threshold 적용 로직 변경: 최고 스코어 클래스가 threshold를 넘지 못하면 background로 처리

`2.0.6`

2023/04/18
[기능 변경]
- Analysis API가 InferenceHandler.analyze() & InferenceHandler.summarize_analysis() 로 변경되었습니다.
- 기존 Analysis API들은 제거되었습니다.

`2.0.5`

2023/04/14
SaigeToolkit 버전 업데이트: 88a43c
- torch 버전 업데이트: 2.0.0+cu118
[기능 추가]
- InferenceHandler.infer_and_postprocess 결과에 이미지가 oversized 인지 여부를 나타내는 is_oversized 추가 (bool)
- CudaOutOfMemoryError 핸들링 추가.
[기능 개선]
- 학습/인퍼런스시 데이터 전처리 최적화를 통해 속도가 향상 되었습니다.

`2.0.4`

2023/04/05
SaigeToolkit 버전 업데이트: c71e88
[기능 추가]
- Trainer.build() 및 Analysis.set_analysis_data()의 데이터 스키마 중 "bounding_box" + "bitmap" 으로 입력하던 라벨을 "contours" 로 입력할 수 있도록 추가
[Bug Fix]
- 인퍼런스 시 특정 이미지 사이즈에서 GPU 메모리 증가하는 이슈 일부 해결 (최대 2MB 까지는 증가할 수 있음)

`2.0.3`

2023/03/29
SaigeToolkit 버전 업데이트: 1b55c9
Toolkit 업데이트에 따라 import segmentation 시간이 40% 정도 감소하였습니다.
[기능 추가]
- InferenceHandler에 params.oversized_image_handling 옵션 추가: do_not_inspect, resize_to_fit, crop_into_tiles
[기능 변경]
- Trainer.build() 중 network_type 키 변경
  - v1_fast → v1_shallow
  - v1_accurate → v1_deep
[Bug Fix]
- Windows에서 num_workers > 0 사용하는 경우 발생하는 에러 해결 (validation worker=0 으로 변경)

`2.0.2`

2023/03/22
[기능 추가]
- Trainer.build()에 V2 network_type 추가: v2_fast, v2_standard, v2_accurate
[기능 변경]
- Trainer.build() 중 network_type 키 변경
  - shallow → v1_fast
  - standard → v1_standard
  - deep → v1_accurate
- Validation 시에도 inspection_size_wh 적용
- InferenceHandler.to_device() 호출 시 warmup 수행
- Trainer.train_one_step() 첫 호출 시 validation 일부 수행해 gpu memory 체크
[Bug Fix]
- Windows에서 Trainer.build시 num_workers=0 사용하는 경우 발생하는 에러 해결
- inspection_size_wh 적용 시에도 gpu memory 사용량이 변하는 이슈 일부 해결

`2.0.1`

2023/03/14
SaigeToolkit 버전 업데이트: f91000
[기능 추가]
- Trainer.build 함수 config dict에 inspection_size_wh가 추가되었습니다.
- InferenceHandler inference_option 추가
  - params.inspection_size_wh 옵션이 추가 되었습니다.
- InferenceHandler에 warmup API가 추가되었습니다.
[기능 변경]
- Trainer.build 함수 config dict에 들어가는 key 값이 변경되었습니다.
  - crop → crop_wh
  - resize_scale → resize_factor
- Trainer 학습 시 데이터 로딩 속도를 올리기 위해 prefetch_factor=8 이 적용되고, 윈도우의 경우 persistent_workers=True로 동작이 변경되었습니다.
- InferenceHandler의 inference_option 변경 사항
  - params.max_batch_size → params.batch_size으로 이름이 변경되었습니다. 인퍼런스 시 항상 params.batch_size를 사용합니다.
  - 인퍼런스 시 고정 GPU 메모리를 사용합니다.
  - params.batch_size와 params.inspection_size_wh은 InferenceHandler.build 시에만 적용 가능하며, set_inference_option 에서는 변경이 불가합니다.
[Bug Fix]
- InferenceHandler에서 시간 측정 기능을 사용할 때, inferece_time이 제대로 측정되지 않던 버그가 해결되었습니다.
- Trainer에서 전체 데이터가 batch_size보다 작은 경우 학습이 진행되지 않는 이슈가 해결되었습니다.
- 내부 알고리즘 변경 (.contiguous())으로 인퍼런스 속도가 향상되었습니다.

`2.0.0`

`rc4`

2023/02/27
SaigeToolkit 버전 업데이트: d7ebf2
[기능 변경]
- InferenceHandler의 리턴 결과에서 logit 제거
[Bug Fix]
- ImageProcessor cythonize시 발생하던 staticmethod 에러 해결

`rc3`

2023/02/20
SaigeToolkit 버전 업데이트: ef67f8
[기능 추가]
- 학습/검사 시 16비트 이미지 지원
- Trainer.post_train_process 메소드 추가
- inference_option 추가
  - outputs.time 추가: 인퍼런스 시간 측정 옵션
  - params.max_batch_size 옵션 추가: InferenceHandler.infer_and_postprocess 에 한 번에 입력할 수 있는 이미지 수 제한 (기본값 1)
  - params.object_score_threshold 추가
  - params.calc_object_area_and_apply_threshold 추가: object의 area를 계산하고 threshold를 적용할지 여부
  - params.calc_object_score_and_apply_threshold 추가: object의 score를 계산하고 threshold를 적용할지 여부
- InferenceHandler.infer_and_postprocess 호출 시 objects 결과 값에 area, score, bounding_box, bounding_rot_box, fitted_ellipse 추가
- InferenceHandler.finalize_analysis 결과 추가
  - images에 이미지 별 object/underkill, object/overkill 추가
  - summary에 object/underkill, object/class_{idx}_underkill 추가
  - summary에 object/overkill, object/class_{idx}_overkill 추가
  - summary에 distribution_of_prediction, class_{idx}_distribution_of_prediction 추가
[기능 변경]
- Trainer.build config 중 model → network_type로 이름 변경
- Augmentation 종류 및 파라미터 변경
  - color_jitter, adjust_brightness_contrast, iso_noise, light_reflect 제거
  - adjust_brightness, adjust_contrast, adjust_hue, adjust_saturation 추가
  - adjust_gamma 파라미터 변경
- inference_option 변경
  - params.score_threshold → params.object_boundary_threshold 로 변경 (default 0 → 100 변경)
  - params.area_threshold → params.object_score_threshold 로 변경
- InferenceHandler.set_analysis_data, Trainer.build 데이터 입력 구조를 list → dict 변경
- InferenceHandler.finalize_analysis 결과 출력 구조를 list → dict 변경
[기능 제거]
- inference_option 중 params.wo_background 제거
[Bug Fix]
- n_classes 가 16 이상인 경우 iou가 잘못 계산되는 오류 해결

`rc2`

SaigeToolkit 버전 업데이트: 482af7
SaigeToolkit의 체크포인트의 구조가 변경되어 빠른 metadata 읽기/쓰기를 지원합니다.
[기능 추가]
- 체크포인트의 metadata 읽기/쓰기를 위한 read_metadata(), write_metadata() API 추가.
- rc1 이후 버전 체크포인트를 최신 버전 구조로 변환하는 convert_checkpoint() API 추가.
[기능 변경]
- InferenceHandler의 inference_options 저장 기능이 사라졌습니다. 이에 따라 InferenceHandler.build() 로 인스턴스 생성 시 이전에 저장했던 inference_options를 자동으로 불러와 사용하는 동작이 제거되었고, 대신 config를 통해 inference_options를 세팅할 수 있도록 변경되었습니다. 따라서 inference_options를 metadata에 저장하고, 이 값을 build시에 읽어서 config에 입력해야합니다.
- inference_options의 옵션들을 각 아이템 별로 세팅할 수 있도록 API가 변경되었습니다.
  - InferenceHandler.get_inference_options() → InferenceHandler.get_inference_option()
  - InferenceHandler.set_inference_options() → InferenceHandler.set_inference_option()
  - InferenceHandler.get_default_inference_options() → InferenceHandler.get_default_inference_option()
[기능 제거]
- InferenceHandler.get_metadata() API 제거.
- InferenceHandler.save_checkpoint() API 제거.

`rc1`

SaigeToolkit 버전 업데이트: 731dbe
설치형 모듈 SaigeError가 추가됨에 따라 환경 설치(pip install -r requirements.txt)를 다시 수행하셔야 합니다.
standard, deep 모델 변경: 학습 속도, 메모리 및 체크포인트 크기가 감소하였습니다. rc0 버전 모델은 지원되지 않습니다.

`rc0`

initial release