局域网用户应选择自己电脑上的数据文件夹，浏览器会把其中的文件上传到过滤服务器。
服务端按原相对目录结构保存上传内容，再执行过滤；源电脑上的视频和轨迹不会被修改。
01
推荐目录结构
每个样本目录必须恰好包含一个可识别视频和一个轨迹文件，独立内参最多一个。
batch_001/
├── sample_001/
│ ├── video.mp4
│ ├── camera_to_world.npz
│ └── intrinsics.npz # 可选
└── sample_002/
├── video.mp4
└── camera_to_world.npz # 也可在此文件内嵌内参
必需
原始视频
*.mp4 / *.mov / *.mkv / *.avi
必须可解码、至少一帧且 FPS 为正。视频帧按原始顺序与轨迹逐帧对应。
必需
相机轨迹
camera_to_world / trajectory / c2w / poses
最终解析为 [T,4,4]。当前采用 absolute c2w：每帧矩阵把相机坐标转换到世界坐标。
可选
相机内参
intrinsics.npy / .npz / .json
形状为全片共享 [3,3] 或逐帧 [T,3,3]，表示归一化针孔相机矩阵 K。
当前为严格对齐：视频帧数必须等于轨迹帧数；逐帧内参也必须对齐。缺少内参时会按 90° 水平 FOV 生成合成内参并在报告中警告。
查看轨迹和内参支持的具体格式
轨迹支持 .npy / .npz / .json / .txt / .csv；可读取 [T,4,4]、[T,3,4]、[T,16] 或 [4T,4]。
NPZ/JSON 轨迹键可为 camera_to_world、c2w、poses、trajectory；内参键可为 intrinsics、K、camera_matrix。
02
HTTP 上传与过滤 API
远程文件夹采用“创建会话 → 逐文件流式上传 → 启动过滤”三步调用。
打开 Swagger ↗
1POST /v1/uploads声明文件夹、文件数和总字节数
2PUT /v1/uploads/{upload_id}/files按 relative_path 逐文件上传二进制内容
3POST /v1/uploads/{upload_id}/filter校验上传完整性并执行十项过滤
创建 · folder_namestring / 必需用户选择的根文件夹名称
创建 · file_count / total_bytesinteger / 必需客户端将要上传的文件数量和总大小
文件 · relative_pathquery string / 必需文件在所选文件夹中的 POSIX 相对路径
过滤 · write_reportboolean / 可选默认 true；是否把 JSON 保存到报告目录
cURL 三步调用示例
服务器本地目录的兼容接口
服务器程序或命令行仍可调用 POST /v1/filter，传入服务器可读取的 input_folder。远程浏览器不能用该接口读取用户电脑路径。
03
API 输出
过滤接口返回批次 JSON 报告，并附带服务端上传目录信息；上传文件会保留用于视频和 Pose 复核。
{
"status": "valid | invalid | error",
"summary": {"total": 2, "valid": 1, "invalid": 1, "error": 0},
"samples": [{
"sample_id": "sample_001",
"status": "invalid",
"input": {"effective_frames": 141, "fps": 24.0, "pose_type": "c2w"},
"rules": [{
"name": "frame_count", "status": "passed", "score": 1.0,
"reasons": [], "duration_ms": 0.021
}],
"filter_score": 0.9
}],
"report_path": "/path/to/report.json",
"upload": {"upload_id": "…", "server_directory": "/path/to/uploads/…"}
}
status批次或样本状态。任一规则失败则样本为 invalid；规则异常优先标记为 error。
rules每种过滤器的状态、二值分、失败原因和执行耗时。通过=1，拒绝=0，异常=null。
filter_score非空规则二值分的平均值，即规则通过比例；它不是模型置信度。
report_pathwrite_report=true 时的服务器报告路径，否则为 null。