v4.5.6

v4.5.6은 대규모 머신러닝 릴리스입니다. TensorFlow tf C 모듈이 TensorFlow Lite Micro(TFLM)를 기반으로 하는 새로운 엔진 독립적 ml 패키지로 대체되었고, 이미지→텐서 변환은 image.to_ndarray() 로 옮겨졌으며, 듀얼 코어 보드는 Open-AMP로 전환되었습니다. 몇 가지 호환성을 깨는 변경 사항이 있으니 ML 스크립트를 업그레이드하기 전에 아래 내용을 읽어 보세요.

주요 내용

  • 새로운 ml 패키지 — 기존 tf 모듈이 엔진 독립적인 ml 패키지(ml.Model, ml.preprocessing, ml.utils, ml.apps)로 재작성되었습니다. tf 는 별칭으로 남아 있습니다.

  • TFLM 백엔드 — 더 이상 사용되지 않는 libtf 가 업스트림 기반 TensorFlow Lite Micro로 대체되었습니다. 추론이 약 20% 빨라지고 라이브러리 크기도 작아졌습니다.

  • Open-AMP 듀얼 코어 — GIGA와 Portenta H7이 이제 M7/M4 코어 간 통신에 Open-AMP/RPMsg를 사용합니다(기존 CM4 메커니즘은 제거됨).

  • 온보드 Bluetooth — CYW43 Bluetooth 펌웨어가 Nicla Vision, Portenta H7, GIGA에서 활성화되었습니다.

  • MicroPython 1.23.0, ulab 6.5.2 (4차원 ndarray 지원 포함).

  • 호환성 변경: ML API가 크게 변경되었으며 대부분의 보드에서 Haar 캐스케이드가 기본적으로 비활성화되었습니다 — 호환성을 깨는 변경 사항을 참고하세요.

새로운 기능

  • ml 패키지 — predict() (roi, callback, 다중 입력 리스트)를 갖춘 ml.Model, 텐서별 shape/dtype/scale/zero-point 속성, ml.preprocessing.Normalization, ml.utils (NMS), 그리고 ml.apps (listen() 과 논블로킹 timeout=-1 스트리밍, draw_predictions() 를 갖춘 순수 Python MicroSpeech 키워드 검출기).

  • 내장 모델 시스템 — models/index.txt 에 나열된 모델이 보드별로 조건부 임베드됩니다(모든 ML 보드에는 FOMO, 마이크가 있는 보드에는 오디오 모델).

  • image.to_ndarray(dtype, buffer=...) — 이미지를 ulab ndarray로 변환합니다(선택적으로 제자리에서).

  • 원시 배열로부터 Image() — 새로운 shape=, strides=, scale= 키워드 인자로 원시 픽셀 리스트에서 grayscale/RGB565 이미지를 생성합니다.

  • 안티앨리어싱된 draw_circle().

  • ssl 모듈이 GIGA, Nicla Vision, Portenta H7, Nano RP2040 Connect, OpenMV 4/4P/PRO/PT, RT1060, Pico의 펌웨어에 고정 포함되었습니다.

  • 오디오 — audio.init() 에 samples= 키워드(채널당 PDM 샘플 수)가 추가되었습니다. gain_db 가 이제 DFSDM 마이크(예: Nicla Vision)에 적용됩니다.

  • 디버그 프로토콜 — 새로운 GET_STATE 명령이 실행/텍스트/JPEG 플래그, 프레임 지오메트리, 텍스트를 단일 패킷으로 반환하여 호스트 왕복 횟수를 줄입니다.

  • 코어 간 통신을 위한 Open-AMP vuart 예제.

기타 변경 및 개선 사항

  • MicroPython이 1.23.0으로 업데이트되었으며, ulab은 4차원 ndarray 지원과 함께 6.5.2로 업데이트되었습니다.

  • 더 빠른 추론 — ML 백엔드가 호출 간에 상태/메모리를 유지합니다(약 20% 빨라지고 LSTM 방식 모델을 지원).

  • get_similarity() 가 draw_image 백엔드 위에서 재구현되었습니다(더 넓은 포맷/연산 지원).

  • morph() 과 mean() 필터 계열이 키워드 인자 파싱으로 옮겨졌으며, mask= 가 이제 변경 가능한 이미지를 받습니다.

  • 메모리 레이아웃 재작업 — DMA 영역이 2의 거듭제곱으로 정렬되고, 재정렬 가능한 GC 블록, 다중 힙이 적용되어 RAM이 적은 보드에서 초기 힙 단편화가 줄어들고 RT1060에는 추가 GC 힙이 생깁니다.

  • 이제 소프트 리셋 시 WiFi(CYW43)가 초기화 해제됩니다. SPI-TV 디스플레이는 더 매끄러운 업데이트를 위해 캐시에서 프레임버퍼 영역만 플러시합니다.

버그 수정

카메라 및 센서:

  • STM32와 i.MX RT의 프레임버퍼/센서 경로에서 이미지 데이터를 손상시킬 수 있는 의도치 않은 CPU 캐시 무효화를 수정했습니다.

  • i.MX RT 보드에서 MLX90640/MLX90641 열화상 I2C 읽기를 수정했습니다(대용량 전송을 이제 청크 단위로 처리).

머신러닝:

  • ml.Model 의 load_to_fb 처리, 입력 bytearray 크기 산정, ndarray ndim 검사, Normalization 의 이미지 포맷/형태 검증을 수정했습니다.

이미지 / 시스템:

  • 누락되어 있던 image.BLACK_BACKGROUND 그리기 힌트 상수와 이미지/텐서 버퍼 길이 정합성 검사를 추가했습니다.

  • 수집기가 사용 중인 버퍼를 해제하게 만들 수 있었던 FIR 및 오디오 GC 루트 포인터를 수정했습니다.

  • Servo Shield 예제가 이제 SoftI2C 를 사용하므로 OpenMV RT 보드에서 동작합니다.

하드웨어 및 보드 지원

  • Arduino GIGA — HM01B0 / HM0360 센서 지원; Open-AMP 듀얼 코어.

  • Bluetooth — Nicla Vision, Portenta H7, GIGA의 CYW43 BT 펌웨어.

  • Portenta H7 — Open-AMP M7/M4 RPMsg.

  • OpenMV RT1060 — 추가 GC 힙 블록(더 많은 Python 메모리).

호환성을 깨는 API 변경 사항

v4.5.5와 v4.5.6 사이의 사용자에게 보이는 API 변경입니다. 범위: modules/ 의 Python C 모듈과 scripts/libraries/ 의 Python 라이브러리.

각 변경 사항에는 그 영향이 태그로 표시되어 있습니다:

  • major — 이를 사용한 대부분의 스크립트를 수정해야 합니다.

  • minor — 좁은 범위의 API; 이를 사용한 스크립트에만 영향을 줍니다.

  • behavior — 동일한 API이지만 결과가 다름; 튜닝된 스크립트를 다시 확인하세요.

  • tooling — 듀얼 코어 / 보드 메커니즘에 영향을 주며, Python API에는 영향을 주지 않습니다.

변경 사항은 이 순서대로 영향별로 그룹화되어 있습니다. 코드를 포팅하기만 하면 된다면, 끝에 있는 마이그레이션 체크리스트 로 건너뛰세요. 각 커밋 해시는 GitHub의 해당 diff로 연결됩니다.

tf 모듈이 ml 패키지로 대체됨 (major)

TensorFlow tf C 모듈이 엔진 독립적인 ml 패키지로 재작성되었습니다(tf 는 하위 호환 별칭으로 유지되지만 새 코드에서는 ml 을 사용해야 합니다). 모듈 수준 함수 tf.load, tf.load_builtin_model 과 detect()/segment()/분류 메서드는 제거되었습니다 — ml.Model 을 생성하고 predict() 를 호출하세요. ml.Model(path) 는 이제 모델만 반환합니다((labels, model) 튜플이 아님). 레이블은 model.labels 속성입니다. predict() 는 이제 (float 튜플이 아니라) ulab ndarray를 반환하고, 다중 입력 모델을 지원하며(리스트를 전달), NMS는 ml.utils 로 옮겨졌습니다. 입력 정규화는 ml.preprocessing.Normalization 으로 옮겨졌습니다. 기존 ml.py 는 이제 ml.apps 입니다.

커밋: c7228cbb4, 6c212409c, 3e37f46db, 9a186f4e2, 70b89f474, 3f8491cb0, 4506682c2, 8b38f3837

image.unpack() 제거됨 — to_ndarray() 사용 (major)

잠시 도입되었던 image.unpack() 이 제거되었습니다. 대신 image.to_ndarray(dtype, buffer=...) 로 이미지를 텐서로 변환하고, 기존 내장 이미지 스케일링 경로 대신 ml.preprocessing.Normalization 으로 scale/mean/stdev 정규화를 적용하세요.

커밋: 9848eed12, de0d46fa6

Image() 원시 배열 scale 인자 (minor)

원시 픽셀 배열로부터 Image 를 생성할 때, scale 인자가 이제 (scale, add) 대신 (min, max) 범위를 받습니다.

커밋: 7b79fb4c7

대부분의 보드에서 Haar 캐스케이드가 기본적으로 비활성화됨 (behavior)

플래시 공간을 확보하기 위해, Haar 캐스케이드 얼굴 검출(find_features() / image.HaarCascade())이 이제 Arduino GIGA, Nicla Vision, Portenta H7, OpenMV 3, OpenMV 4 / 4 Plus / PRO, OpenMV Pure Thermal에서 기본적으로 비활성화됩니다. 이러한 보드에서 Haar 캐스케이드를 사용하는 스크립트는 해당 기능을 활성화하여 펌웨어를 다시 빌드해야 합니다.

커밋: 6ce27c910

스크립트 중단과 텐서 스케일링 (behavior)

USB 디버거가 이제 강제 PendSV 점프 대신 MicroPython의 VM 중단(abort) 기능을 통해 실행 중인 스크립트를 중단시킵니다(더 깔끔하지만 중단 지점이 다릅니다). SCALE_S128_127 입력 스케일링이 잘못된 게인 없이 0–255를 −128–127로 매핑하도록 수정되었습니다 — 기존의 (잘못된) 스케일링에 의존하던 모델은 다른 결과를 만들어 냅니다.

커밋: e758a0f95, a4d97c572

CM4 코프로세서가 Open-AMP로 대체됨 (tooling)

GIGA / Nicla Vision / Portenta H7의 더 이상 권장되지 않는 CM4 코프로세서 펌웨어 메커니즘이 제거되고 Open-AMP/RPMsg로 대체되었습니다. 듀얼 코어 코드는 Open-AMP 모델로 옮겨야 합니다(vuart 예제가 제공됩니다).

커밋: 3cc57fea4, 93f2d4c41

마이그레이션 체크리스트

v4.5.6으로 깔끔하게 포팅하기 위한 일반적인 작업은 다음과 같습니다:

  1. ML 코드를 ml 로 포팅하세요: ml.Model(path) 를 생성하고, predict() 를 호출하며, model.labels 를 읽고, ndarray 출력을 기대하며, 정규화는 ml.preprocessing.Normalization 으로, NMS는 ml.utils 로 옮기세요 (ml 패키지 변경).

  2. image.unpack() 을 image.to_ndarray() 로 교체하세요 (unpack 제거).

  3. Image() 원시 배열의 scale 인자를 (min, max) 범위로 업데이트하세요 (Image scale 변경).

  4. 영향을 받는 보드에서 Haar 캐스케이드를 사용한다면, 해당 기능을 활성화하여 다시 빌드하세요 (Haar 캐스케이드 변경).

  5. SCALE_S128_127 에 의존하던 모델을 다시 검증하세요 (스케일링 변경).

  6. 듀얼 코어 코드를 Open-AMP로 옮기세요 (CM4 변경).