# 接口说明

## 开集目标检测接口使用说明

目标检测模型，可称为openset-detection

### 预测

1. POST: http://{HOST}:{openset-detection-port}/predict
2. 参数: 
``` json
# multipart/form-data
{
    sam_type: "sam2.1_hiera_small", # 固定传入该值
    box_threshold: "0.3", # 传入0-1之间的浮点数字符串
    text_threshold: "0.4", # 传入0-1之间的浮点数字符串
    text_prompt: "person." # 描述需要识别的物体
    expect_response_type: "image" | "mask" | "information", # 枚举
    image: UploadFile # 图像文件
}
```
3. 返回结果
若expect_response_type字段为"image"或者"mask"，则response.content部分为返回的标注后的图片文件，python示例代码：
``` python
if response.status_code == 200:
    try:
        print("response image")
        print(len(BytesIO(response.content).getvalue()))
        output_image = Image.open(BytesIO(response.content)).convert("RGB")
        return output_image
    except Exception as e:
        print(f"Failed to process response image: {e}")
        return None
```
若expect_response_type字段为"information"，返回结果则为json格式数据:
``` json
{
    boxes: [[x1, y1, x2, y2]] # 包围盒bbox的左上角和右下角坐标
    scores: [0.0] # 一维浮点数列表，置信度
    labels: ['person'] # 一维字符列表，识别到的目标标签
}
```
返回的三个字段，列表长度是对齐的

4. 具体使用流程
若需要识别溺水人员，首先需要识别场景中的人，修改字段text_prompt为"person."，发起第一轮请求进行人员识别，利用返回的boxes适当增加包围盒大小从原始图片中截取子图，修改字段text_prompt为"drown."，对子图发起第二轮请求进行溺水识别，得到最终结果。**若结果中包含了置信度低的不理想检测，可调高box_threshold字段进行抑制，sam_type和text_threshold不可改变**


## 分类模型

分类模型，可称为classification-model

### 滑坡预测
1. POST: http://{HOST}:{classification-model-port}/resnet18
2. 参数: 
``` json
# multipart/form-data
{
    file: UploadFile # 图像文件
}
```
3. 返回结果
``` json
{
  "cls_label": "string", # 分类器1的结果标签, 可能是['earthquake', 'fire', 'flood', 'hurricane', 'landslide', 'not_disaster', 'other_disaster']
  "cls_probability": 0.0, # 分类器1的结果标签置信度
  "clip_label": "string", # 分类器2的结果标签, 可能是['normal', 'landslide']
  "clip_probability": 0.0, # 分类器2的结果标签置信度
  "cls_landslide_prob": 0.0, # 分类器1的滑坡置信度（额外）
  "clip_landslide_prob": 0.0 # 分类器2的滑坡置信度（额外）
}
```
前四个字段是常规字段，分别是两个分类器的预测结果和置信度，额外的字段可以忽略

### 桥梁塌陷预测
1. POST: http://{HOST}:{classification-model-port}/bridge
2. 参数: 
``` json
# multipart/form-data
{
    file: UploadFile # 图像文件
}
```
3. 返回结果
``` json
{
  "label": "string", # 类别，可能是['normal', 'broken_bridge']
  "probability": 0.0 # 置信度
}
```