ndarray

NumPy ndarray：dtype、shape、切片与视图、广播与轴运算、线性代数；与 list 区别及常见坑；链回 OpenCV 与官方手册。

numpy.ndarray 是 NumPy 的 N 维数组：同质 dtype、连续内存、向量化 运算（C 层批量执行，常释放 GIL）。科学计算、OpenCV cv2 图像矩阵、机器学习张量都基于它。标准库无 ndarray，需 pip install numpy。

pip install numpy

适用性：Pyodide 可装 NumPy，但包体大、加载慢；超大数组受 WASM 内存限制。

何时用 ndarray

场景	建议
数值向量、矩阵、批量运算	`ndarray` + ufunc，避免纯 Python 循环
与 cv2、pandas、torch 交互	多数通过 `ndarray` 或共享 buffer
少量异构数据、频繁变长拼接	先用 `list`，再一次 `np.array()`
需要键值、嵌套对象	用 `dict` / dataclass，或 `dtype=object`（慢）

视图 vs 拷贝：切片常为视图，改切片会改原数组；独立数据用 .copy()。

广播：形状按维对齐，长度为 1 的维可「拉伸」参与运算，避免手写嵌套循环。

模块成员总览

创建数组

名称	返回值 / 类型	说明
`array(obj, dtype=)`	`ndarray`	从 list、嵌套序列等构造
`zeros` / `ones` / `full`	`ndarray`	填 0 / 1 / 指定值
`empty(shape)`	`ndarray`	未初始化（快）
`arange(start, stop, step)`	`ndarray`	类似 `range`
`linspace(start, stop, num)`	`ndarray`	等分点
`eye(n)` / `identity(n)`	`ndarray`	单位矩阵
`random.default_rng().random(...)`	`ndarray`	随机数（推荐新 API）

形状与类型

名称	说明
`ndim` / `shape` / `size`	维数、各维长度、元素总数
`dtype` / `astype(...)`	元素类型 / 转换（常拷贝）
`reshape` / `ravel` / `flatten`	改形状；`ravel` 多视图，`flatten` 拷贝
`T` / `transpose`	转置

索引与组合

名称	说明
切片 `a[i:j]`	通常视图
布尔掩码 `a[a > 0]`	筛选，一般新数组
花式索引 `a[[0, 2]]`	整数数组索引，一般拷贝
`concatenate` / `vstack` / `hstack` / `stack`	拼接
`split`	拆分

运算与线性代数

名称	说明
ufunc（`+`、`*`、`np.sin` 等）	逐元素；遵守广播
`sum` / `mean` / `max` + `axis`	沿轴聚合
`dot` / `@` / `matmul`	矩阵乘
`linalg.solve` / `inv` / `svd`	解方程、分解

持久化

名称	说明
`save` / `load`	单数组 `.npy`
`savez` / `load`	多数组 `.npz`
`savetxt` / `loadtxt`	文本

创建与基本属性

import numpy as np

a = np.array([1, 2, 3])
grid = np.array([[1, 2], [3, 4]])
z = np.zeros((2, 3), dtype=np.float32)

print(a.dtype, a.shape, a.ndim)

dtype 与 shape

常见 `dtype`	含义
`int32` / `int64`	有符号整数
`uint8`	无符号 8 位（图像常见）
`float32` / `float64`	浮点

a = np.arange(12).reshape(3, 4)
b = a.reshape(2, -1)   # -1 表示自动推断该维

C 顺序（默认）：最后一维变化最快；order='F' 为列优先。
int + float 运算结果提升为浮点；溢出按 C 规则，非 Python 大整数。

索引与切片

m = np.arange(12).reshape(3, 4)
m[1, 2]           # 标量
m[1, :]           # 第 2 行
m[:, 1]           # 第 2 列
m[0:2, 1:3]       # 子矩阵
m[m > 5]          # 布尔索引 → 一维

x = np.arange(5)
y = x[1:4]
y[:] = 99
# x 变为 [0, 99, 99, 99, 4]

方式	结果
整数索引	降维标量
切片	多为视图
布尔 / 花式索引	多为新数组或拷贝

广播与向量化

a = np.array([[1], [2], [3]])   # (3, 1)
b = np.array([10, 20, 30])      # (3,)
c = a + b                       # (3, 3)

从 最后一维 向前对齐：相等或其一为 1 才可广播；否则 ValueError。np.broadcast_shapes 可预览结果形状。

m = np.arange(12).reshape(3, 4)
m.sum(axis=0)   # 每列求和 → shape (4,)
m.sum(axis=1)   # 每行求和 → shape (3,)

axis=0 沿行方向聚合（逐列）；记不准时用 keepdims=True。

线性代数（常用）

A = np.array([[1.0, 2], [3, 4]])
b = np.array([5.0, 6])
x = np.linalg.solve(A, b)

高维 @ 对最后两维做批量矩阵乘。

持久化与互操作

np.save("arr.npy", a)
a2 = np.load("arr.npy")

lst = a.tolist()
s = np.array(3)
v = s.item()   # Python 标量

模块	关系
NumPy	包总览：子模块、ufunc、随机、FFT 等
`cv2`	图像即 `ndarray`；见 opencv-cv2
`array`（标准库）	定长数值缓冲；与 `ndarray` 可 `memoryview` 协作
`pandas`	表格式数据，底层常基于 NumPy
`threading` / `multiprocessing`	大数组并行注意 GIL 与拷贝成本

易错点（排错速记）

切片改到原数组：视图；要副本用 .copy()。
a += 1 与视图：可能原地改，与 dtype、内存布局有关。
axis 方向搞反：用 keepdims=True 看中间形状。
浮点 ==：用 np.isclose。
if arr:：报错；用 arr.size 或 arr.any()。
大数组循环 append：预分配或 list 后一次 array()。
reshape 元素总数不一致：size 必须不变。

资料：NumPy 用户指南 · ndarray · 广播