OpenMV MicroPython numpy --- 與 numpy 相容的陣列運算¶
ulab 的 numpy 子模組提供一套與 numpy 相容的 API，圍繞 ndarray n 維陣列型別建構。它實作了 CPython numpy 經精選的子集：陣列建構、逐元素數學運算、歸約與統計、線性代數、FFT、亂數產生、多項式擬合，以及基本 I/O。
此子模組依慣例匯入為 np:
from ulab import numpy as np
a = np.array([1, 2, 3, 4], dtype=np.float)
b = np.linspace(0, 1, num=5)
c = np.dot(a.reshape((2, 2)), a.reshape((2, 2)))
每個 dtype 引數是模組層級公開的整數常數之一：numpy.bool、numpy.uint8、numpy.int8、numpy.uint16、numpy.int16 和 numpy.float（預設值）。結果型別 ndarray 指的是 numpy.ndarray。
子模組¶
class ndarray --- n 維陣列¶
ndarray 是 numpy / ulab 核心的 n 維、可感知 dtype 的容器。資料儲存在一塊連續的記憶體區塊中，其解讀方式由一個小型標頭描述（dtype、shape、strides、ndim、itemsize）。許多運算——reshape、transpose、切片——只會調整這個標頭，因此非常廉價；而會配置新儲存空間的方法（copy、flatten、大部分算術運算）則回傳一個新的稠密陣列。
同一型別可透過 ulab.ndarray、numpy.ndarray，以及（在本頁中）直接以 ndarray 來存取。
- class numpy.ndarray(values: ndarray | bytes | list | tuple, *, dtype: int = numpy.float)¶
建立一個新的
ndarray。- 參數:
values -- 來源資料。可以是另一個
ndarray（會被深度複製，若dtype不同則進行型別轉換），或是任何 MicroPython 可迭代物件。巢狀的可迭代物件會產生多維陣列；內層的可迭代物件必須全部具有相同長度，否則會引發ValueError。dtype -- 新陣列的元素型別。
numpy公開的型別代碼整數之一（numpy.bool、numpy.uint8、numpy.int8、numpy.uint16、numpy.int16和numpy.float），或dtype實例。預設為numpy.float。
工廠函式
numpy.array是建立ndarray的慣用方式；它會轉呼叫此建構式。- byteswap(*, inplace: bool = False) ndarray¶
交換每個元素的位元組順序。對於
uint16、int16和float陣列，這將反轉每個元素的位元組順序，在處理來自位元組順序與微控制器不同的周邊裝置資料時非常有用。對於單位元組型別（bool、uint8、int8），這是一個無操作，傳回視圖或副本。若
inplace為False（預設值），則回傳一個新的ndarray，原陣列保持不變。若inplace為True，則就地交換self的位元組，並回傳self的一個視圖。
- flatten(*, order: str = 'C') ndarray¶
回傳陣列的一個全新一維副本。
- 參數:
order --
'C'（預設值）以 C 順序走訪資料（最後一軸變化最快）；'F'以 Fortran 順序走訪（第一軸變化最快）。
- reshape(shape: int | tuple[int, ...]) ndarray¶
回傳具有新形狀的陣列視圖。元素總數必須維持不變，否則會引發
ValueError。僅在ULAB_MAX_DIMS > 1時可用。等同於對shape進行賦值。
- tobytes() bytearray¶
回傳一個別名指向陣列底層資料緩衝區的
bytearray。透過回傳的bytearray寫入會就地修改陣列。若陣列並非稠密（例如為切片視圖）則引發ValueError。
- T: ndarray¶
陣列的轉置；等同於
transpose()。
支援的運算子¶
ndarray 實例支援以下運算子。二元運算子依照 numpy 標準廣播規則對運算元進行廣播，並遵循 numpy 的型別提升規則（例如 uint8 + int8 => int16、uint16 + int16 => float）。
算術運算（二元）： +、-、*、/、//、%、**。同時支援反射（右側）運算元和原地變體 +=、-=、*=、/=、%=、**=。ndarray-與-ndarray 和 ndarray-與-純量兩種形式均可接受。
比較： ==、!=、<、<=、>、>=。每個運算子皆回傳一個廣播形狀的布林 ndarray。
位元運算（僅限整數陣列）： &、|、^。將這些操作套用於 float 陣列會引發 TypeError。
一元： +（回傳副本）、-（取負；對無號 dtype，數值會以模 \(2^N\) 環繞）、abs()（逐元素絕對值；對無號 dtype 回傳副本而不進行計算）、~（位元反相，僅限整數 dtype）、len()（回傳第一軸的長度）。
索引與切片： a[i]、a[i, j, ...]、a[start:stop:step]、布林遮罩索引（a[mask]）以及整數陣列（花式）索引在讀取與寫入時皆受支援。
迭代： 迭代 ndarray 會沿第一軸產出子陣列（對 1 維陣列則一次產出一個元素）。請使用 flat 來迭代每個純量元素，不受維度影響。
矩陣乘法運算子 @ 未實作；請改用 numpy.dot（np.dot(a, b)）。
位移運算子（<<、>>）未在運算子層級實作。逐元素整數位移請使用 numpy.left_shift 與 numpy.right_shift。
陣列建構¶
- numpy.array(values: ndarray | list | tuple, *, dtype: int = float) ndarray¶
從一個巢狀的數字可迭代物件建構一個新的
ndarray。numpy.ndarray的等效替代建構式。
- numpy.arange(start: int | float, stop: int | float | None = None, step: int | float = 1, *, dtype: int | None = None) ndarray¶
在半開區間
[start, stop)上回傳間隔均勻的值。若只給定一個位置引數，則將其視為stop並令start = 0。若省略 dtype，則由輸入推斷（若 start、stop、step 皆為整數且在範圍內，則為整數）。
- numpy.asarray(a: ndarray | list | tuple, *, dtype: int | None = None) ndarray¶
若 a 已是 dtype 與 dtype 相符的
ndarray（或 dtype 為None），則原樣回傳 a；否則建立一個新陣列（給定時進行所要求的 dtype 轉換）。可迭代物件的轉換方式與numpy.array相同。
- numpy.concatenate(arrays: tuple, *, axis: int = 0) ndarray¶
沿既有的 axis 連接一系列
ndarray。所有輸入陣列必須共享相同的 dtype、ndim，以及除 axis 之外每一軸上的形狀。
- numpy.diag(a: ndarray, *, k: int = 0) ndarray¶
對於 2 維的 a，回傳一個包含第 k 條對角線的 1 維陣列。對於 1 維的 a，回傳一個 2 維方陣，並將 a 置於第 k 條對角線上。k 可為正（主對角線之上）或負（主對角線之下）。
- numpy.empty(shape: int | tuple[int, ...], *, dtype: int = float) ndarray¶
zeros的別名；回傳一個以 shape 和 dtype 為形狀型別且填零的陣列。（ulab 不會讓緩衝區未初始化。）
- numpy.eye(N: int, M: int | None = None, k: int = 0, *, dtype: int = float) ndarray¶
回傳一個 2 維 N x M 陣列（若 M 為
None則為 N x N 方陣），第 k 條對角線為 1，其餘為 0。
- numpy.frombuffer(buffer: bytes, *, dtype: int = float, count: int = -1, offset: int = 0) ndarray¶
將一個遵循緩衝區協定的物件解讀為 dtype 的 1 維
ndarray。count 是要讀取的項目數（-1讀取所有可用項目）；offset 會略過緩衝區開頭那麼多的位元組。
- numpy.full(shape: int | tuple[int, ...], fill_value: int | float | bool, *, dtype: int = float) ndarray¶
回傳一個以 shape 和 dtype 為形狀型別、每個元素皆設為 fill_value 的新陣列。
- numpy.linspace(start: float, stop: float, num: int = 50, *, endpoint: bool = True, retstep: bool = False, dtype: int = float) ndarray | tuple[ndarray, float]¶
在閉區間
[start, stop]上傳回 num 個均勻間隔的樣本（若 endpoint 為False則為半開區間）。當 retstep 為True時，傳回元組(samples, step)。
- numpy.logspace(start: float, stop: float, num: int = 50, *, base: float = 10.0, endpoint: bool = True, dtype: int = float) ndarray¶
回傳 num 個在對數刻度上間隔均勻的取樣點：結果起於
base ** start，終於base ** stop。
- numpy.meshgrid(*xi: ndarray, indexing: str = 'xy') tuple[ndarray, ...]¶
從一系列一維座標陣列回傳一個座標矩陣元組。當 indexing 為
'xy'（預設值）時，前兩個輸入被視為笛卡兒座標，其輸出軸會互換；當為'ij'時則使用矩陣式索引。其實作對應於 NumPy 中copy=True且sparse=False的等效行為。
檢視 / 列印¶
比較¶
- numpy.clip(a: ndarray | int | float, a_min: ndarray | int | float, a_max: ndarray | int | float) ndarray | int | float¶
裁剪 a 的值，使得
a_min <= result <= a_max。等同於maximum(a_min, minimum(a, a_max))；廣播遵循與minimum相同的規則。
- numpy.equal(x1: ndarray | int | float, x2: ndarray | int | float) ndarray | bool¶
逐元素
x1 == x2；回傳一個布林ndarray（若兩個輸入皆為純量則回傳bool純量）。為可攜性而提供——對陣列使用==運算子可得到相同結果。
- numpy.not_equal(x1: ndarray | int | float, x2: ndarray | int | float) ndarray | bool¶
逐元素
x1 != x2；equal的布林對應運算。
- numpy.maximum(x1: ndarray | int | float, x2: ndarray | int | float) ndarray | int | float¶
兩個陣列／純量的逐元素最大值。引數會一起進行廣播；若 dtype 不同，則輸出會向上提升型別。
數值歸約¶
- numpy.all(a: ndarray | list | tuple, *, axis: int | None = None) ndarray | bool¶
測試沿 axis 的所有元素是否皆為
True。當axis=None（預設值）時，測試展平後的陣列並回傳單一bool。
- numpy.any(a: ndarray | list | tuple, *, axis: int | None = None) ndarray | bool¶
測試沿 axis 是否有任何元素為
True。當axis=None時，測試展平後的陣列。
- numpy.argmax(a: ndarray | list | tuple, *, axis: int | None = None) ndarray | int¶
回傳沿 axis 最大元素的索引。當
axis=None時，陣列會被展平並回傳單一整數。
- numpy.argmin(a: ndarray | list | tuple, *, axis: int | None = None) ndarray | int¶
回傳沿 axis 最小元素的索引。當
axis=None時，陣列會被展平並回傳單一整數。
- numpy.argsort(a: ndarray, *, axis: int = -1) ndarray¶
回傳一個無號整數索引
ndarray，其各項可將 a 沿 axis 以遞增順序排序。輸出 dtype 為uint16，因此任何軸都不得超過 65535 個元素。不支援axis=None。
- numpy.diff(a: ndarray, *, n: int = 1, axis: int = -1) ndarray¶
回傳 a 沿 axis 的第 n 階離散前向差分。n 必須在
0..9之間（差分模板儲存於int8中）；axis 的長度會縮減 n。numpy 的prepend與append關鍵字未實作。
- numpy.flip(a: ndarray, *, axis: int | None = None) ndarray¶
回傳一個新陣列，元素沿 axis 順序反轉；當
axis=None時，陣列沿每一軸皆反轉。
- numpy.max(a: ndarray | list | tuple, *, axis: int | None = None, keepdims: bool = False) ndarray | int | float¶
回傳沿 axis 的最大元素。當
axis=None（預設值）時，展平後的陣列會被歸約為一個純量。numpy 的out關鍵字未實作。
- numpy.min(a: ndarray | list | tuple, *, axis: int | None = None, keepdims: bool = False) ndarray | int | float¶
回傳沿 axis 的最小元素；
max的對應運算。
- numpy.mean(a: ndarray | list | tuple, *, axis: int | None = None, keepdims: bool = False) ndarray | float¶
回傳沿 axis 的算術平均值。當
axis=None（預設值）時，回傳展平後陣列的平均值，型別為float。
- numpy.median(a: ndarray, *, axis: int | None = None) ndarray | float¶
回傳沿 axis 的中位數。當
axis=None時，陣列會先被展平。輸出 dtype 永遠為 float。
- numpy.roll(a: ndarray, shift: int, *, axis: int | None = None) ndarray¶
回傳 a，其元素被滾動（循環移位）shift 個位置。當
axis=None（預設值）時，陣列會先被展平。負位移會以相反方向滾動。
- numpy.sort(a: ndarray, *, axis: int = -1) ndarray¶
使用堆積排序回傳 a 沿 axis 的已排序副本。當
axis=None時，陣列會先被展平。numpy 的kind與order關鍵字未實作。
統計¶
轉換¶
- numpy.compress(condition: ndarray | list | tuple, a: ndarray, *, axis: int | None = None) ndarray¶
回傳 a 中由布林 condition 沿 axis 所選取的切片。當
axis=None時，使用展平後的陣列。
近似¶
選取¶
位元運算¶
濾波¶
多項式¶
I/O¶
- numpy.load(file: str) ndarray¶
從 file 讀取先前以
save寫入的陣列（numpy 與平台無關的.npy格式）。若檔案的位元組序與主機不同，則會即時轉換位元組序。
- numpy.loadtxt(file: str, *, delimiter: str | None = None, comments: str = '#', max_rows: int = -1, usecols: int | ndarray | list | tuple | None = None, dtype: int = float, skiprows: int = 0) ndarray¶
從文字 file 讀取數值資料，並以
ndarray形式回傳。delimiter 預設為空白字元；comments 是行內註解標記；max_rows 限制讀取的資料列數（-1表示全部）；usecols 依索引選擇欄；skiprows 略過那麼多的開頭列。若 dtype 不是 float，數值會以四捨五入方式轉換。
通用函式¶
逐元素數學函式。每個函式接受一個純量或一個 ndarray，並回傳形狀相符的結果（純量輸入回傳 float 純量，陣列輸入回傳 ndarray）。當以 ndarray 呼叫時，結果是一個新的浮點 ndarray；可傳入一個可選的 out 關鍵字，將結果寫入一個預先配置且大小相同的 float ndarray。
- numpy.arctan2(y: ndarray | float, x: ndarray | float, /) ndarray | float¶
逐元素計算雙引數反正切
atan2(y, x)；支援兩個輸入之間的廣播。