Jupyter 基本使用及 ForIM 平台接入指南

一、Jupyter 基本使用

1. .ipynb 文件简介

.ipynb 是 Jupyter Notebook 使用的标准文件格式，全称为 IPython Notebook （尽管现已支持多种编程语言，名称仍沿用）。该格式基于 JSON（JavaScript Object Notation） ，用于存储交互式计算文档，内容可包含：

• 可执行代码（如 Python、R）
• Markdown 格式的说明文本
• 运行结果（文本、表格、图像、图表等）
• 公式（LaTeX）
• 元数据（内核信息、作者、环境配置等）

2. .ipynb 文件结构

一个 .ipynb 文件本质上是一个结构化的 JSON 对象，主要由以下部分组成：

2.1 元数据（metadata）

记录 Notebook 的全局配置信息，例如：

• 使用的内核（如python3、ir）
• 内核显示名称
• Notebook 创建/修改时间（部分环境支持）

2.2 单元格（cells）

Notebook 的核心内容单元，每个单元格具有类型和内容。支持以下类型：

每个单元格还包含：

• source：单元格的原始内容（字符串列表）
• execution_count：代码单元格的执行序号（仅 Code 类型）
• outputs：代码执行后的输出结果（仅 Code 类型）

3. 示例：简化版 .ipynb 内容

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": "# 我的第一个 Notebook\n这是一个说明文字。"
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "source": "print('Hello, Jupyter!')",
      "outputs": [
        {
          "output_type": "stream",
          "text": "Hello, Jupyter!\n"
        }
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}

⚠️ 提示 ：虽然 .ipynb 是纯文本 JSON 文件，但不建议手动编辑 ，应通过 Jupyter 界面操作以避免格式错误。

4. .ipynb 的核心优势

• 交互性强 ：支持逐单元格执行，即时查看结果，适合探索性数据分析。
• 文档与代码融合 ：通过 Markdown 单元格撰写说明，实现“可执行文档”。
• 内嵌可视化 ：图表、图像可直接显示在 Notebook 中。
• 可复现性高 ：完整记录分析流程，便于教学、协作与审计。
• 多语言支持 ：除 Python 外，还支持 R、Julia、Scala 等（需安装对应内核）。

5. 使用注意事项

6. 常用操作快捷键（Jupyter Notebook）

命令模式 ：按 Esc 进入，此时可使用字母快捷键；按 Enter 进入编辑模式。

7. 常用包管理命令（推荐使用清华镜像源）

# pip 安装（指定清华源）
pip install <package_name> -i https://pypi.tuna.tsinghua.edu.cn/simple

# conda 安装（添加清华镜像源）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/

# 安装包示例
conda install -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ rasterio

二、ForIM 平台接入指南

ForIM 是一个支持栅格与矢量数据管理的平台。通过 forim_python_sdk，可在 Jupyter Notebook 中便捷地读写 ForIM 表数据。

1. 接入步骤

步骤 1：上传并安装 SDK

将 forim_python_sdk-0.1.0-py3-none-any.whl 文件上传至 Jupyter 工作目录，然后执行：

# 安装依赖 rasterio（推荐使用 conda）
conda install -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ rasterio

# 卸载旧版本（如有）
pip uninstall forim_python_sdk -y

# 强制重装 SDK（路径根据实际调整）
pip install --force-reinstall --no-cache-dir "./forim_python_sdk-0.1.0-py3-none-any.whl"

步骤 2：导入所需类

from forim_python_sdk import ForIMAPIConfig, ForIMAPI, ForIMTable

• ForIMAPIConfig：配置类，用于设置认证信息（如 token）。
• ForIMAPI：API 封装类，提供数据读写接口。
• ForIMTable：数据封装类，.metaData 为元数据，.data 为实际数据。

步骤 3：初始化 API 实例

token = "6bf144edf1a6b613892192c96534ef6b"   # 替换为你的有效 token
options = ForIMAPIConfig(token=token)
forimApi = ForIMAPI(config=options)

table_id = "68f71f56499dc6965c971dd7"        # 目标表 ID

2. 核心接口说明

2.1 分页查询数据

params = {"pageSize": 10, "current": 1}
data_page = forimApi.queryPage(id=table_id, params=params)

metaData = data_page.metaData   # 表元数据
data = data_page.data   # 当前页数据

2.2 查询全量数据

dataset_item = forimApi.queryList(id=table_id)
metaData = dataset_item.metaData
data = dataset_item.data

2.3 从 GeoTIFF 文件写入 ForIM

tif_file = "./data/bio1.tif"
data_item = ForIMTable.fromFile(tif_file)  # 自动解析为 ForIMTable 对象

result = forimApi.itemsCreate(id=table_id, data=data_item)

2.4 从 GeoJSON 数据写入 ForIM

geojson_data = [
    {
        "band_1": "2.5",
        "geometry_area": 6.944444444444451e-5,
        "geometry_bbox": [130.50089337433343, 43.642730090022, 130.50922670766676, 43.65106342335533],
        "geometry": {
            "type": "Polygon",
            "coordinates": [[
                [130.50089337433343, 43.65106342335533],
                [130.50922670766676, 43.65106342335533],
                [130.50922670766676, 43.642730090022],
                [130.50089337433343, 43.642730090022],
                [130.50089337433343, 43.65106342335533]
            ]]
        }
    }
    # ... 更多要素
]

result = forimApi.itemsCreate(id=id, data=geojson_data)

3. 表元数据结构示例

ForIM 栅格表的元数据包含关键地理信息：

{
  "id": "68f71f56499dc6965c971dd7",
  "tableName": "f_r_test_tiff1",
  "tableTitleName": "测试栅格表",
  "tableType": "30",  // 10: 普通表, 20: 矢量空间表, 30: 栅格表
  "systemId": "68552b8dfabfa762deaf9834",
  "tableFieldCounts": 6,
  "additionalProperties": {
    "rasterMeta": {
      "bandCount": 1,
      "crs": "EPSG:4214",
      "dataType": ["float32"],
      "height": 67,
      "width": 134,
      "transform": [
        129.9425600410001,   // xMin
        43.092730090022,     // yMin
        131.05922670766677,  // xMax
        43.65106342335533,   // yMax
        0.00833333333333339, // xRes (像素宽度)
        0.008333333333333285 // yRes (像素高度)
      ]
    }
  }
}

4. 栅格数据格式说明

ForIM 中的栅格数据使用PythonSDK读取后以 三维 NumPy 数组 形式表示，形状为 (bands, height, width)，与 rasterio 读取结果一致：

# 示例数据（shape=(1, 67, 134), dtype=float32）
array([[[-3.402823e+38, -3.402823e+38, ..., -3.402823e+38],
        ...,
        [-3.402823e+38, -3.402823e+38, ..., -3.402823e+38]]])

注：-3.402823e+38 通常表示 NoData 值（如 float32 的最小值）。

5. 使用 rasterio 解析 GeoTIFF 文件（参考）

import rasterio

filepath = "./data/bio1.tif"
with rasterio.open(filepath) as src:
    # 获取地理变换参数
    transform = src.transform
    x_min, y_max = transform * (0, 0)           # 左上角
    x_max, y_min = transform * (src.width, src.height)  # 右下角
    x_res = transform.a
    y_res = -transform.e  # 注意：y 方向通常为负

    # 读取数据
    data = src.read()  # shape: (bands, height, width)

    # 构建元数据（供 ForIM 使用）
    raster_meta = {
        "width": src.width,
        "height": src.height,
        "bandCount": src.count,
        "dataType": src.dtypes,
        "transform": [x_min, y_min, x_max, y_max, x_res, y_res],
        "crs": src.crs.to_string() if src.crs else "EPSG:4490"
    }