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 会沿第一个轴产出子数组（对于一维数组，每次产出一个元素）。使用 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。所有输入数组在除 axis 之外的每个轴上都必须具有相同的 dtype、ndim 和形状。
- numpy.diag(a: ndarray, *, k: int = 0) ndarray¶
对于二维的 a，返回一个包含第 k 条对角线的一维数组。对于一维的 a，返回一个二维方阵，其中 a 放置在第 k 条对角线上。k 可以为正（主对角线之上）或为负（主对角线之下）。
- numpy.empty(shape: int | tuple[int, ...], *, dtype: int = float) ndarray¶
zeros的别名；返回一个形状为 shape、dtype 为 dtype 的全零填充数组。（ulab 不会让缓冲区保持未初始化状态。）
- numpy.eye(N: int, M: int | None = None, k: int = 0, *, dtype: int = float) ndarray¶
返回一个二维 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 为 dtype 的一维
ndarray。count 是要读取的项数（-1读取所有可用项）；offset 会跳过缓冲区起始处的相应字节数。
- numpy.full(shape: int | tuple[int, ...], fill_value: int | float | bool, *, dtype: int = float) ndarray¶
返回一个形状为 shape、dtype 为 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，其各项可沿 axis 将 a 按升序排序。输出 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 始终为浮点型。
- 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.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 不是浮点型，则通过取整转换值。
通用函数¶
逐元素数学函数。每个都接受一个标量或一个 ndarray，并返回一个形状匹配的结果（标量输入返回浮点标量，数组输入返回 ndarray）。当以 ndarray 调用时，结果是一个新的浮点 ndarray；可以传入一个可选的 out 关键字，将结果写入一个预分配的、相同大小的浮点 ndarray。
- numpy.arctan2(y: ndarray | float, x: ndarray | float, /) ndarray | float¶
逐元素计算双参数反正切
atan2(y, x)；支持两个输入之间的广播。