使用说明

地形阴影框

生成3D可打印地形阴影框的MCP（模型上下文协议）服务器。给定一个地理区域，它获取真实的高程数据和OpenStreetMap特征，然后生成多材质3MF文件，准备进行切片和打印。

特性

来自AWS Terrain RGB高程图块的地形网格（免费，全球覆盖）
OpenStreetMap覆盖：道路、水体和建筑物
GPX轨迹可视化为地形上的凸起条带
多种输出形状：正方形、圆形、六边形、矩形
导出到3MF（多材料），OpenSCAD .scad，或SVG地图插入
通过本地Three.js查看器（端口3333）进行实时3D预览
会话保存/加载以在服务器重新启动时恢复工作

安装

从GitHub Release下载预构建的二进制文件，或使用Go从源代码构建：

cd go
go build -o /usr/local/bin/topo-shadow-box ./cmd/topo-shadow-box

添加到克劳德代码

/plugin marketplace add huslage/topo-shadow-box
/plugin install topo-shadow-box@topo-shadow-box

安装插件时，MCP服务器会自动启动。

添加到Codex

将此添加到 ~/.codex/config.toml:

[mcp_servers.topo-shadow-box]
command = "topo-shadow-box"
args = ["serve"]

然后重新启动Codex。

权限

克劳德第一次调用每个工具时，都会请求许可。点击 “始终允许” （不是“允许”），因此批准已保存，不会再次询问您。

如果你想提前批准所有事情，请将此添加到你的 ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__plugin_topo-shadow-box_topo-shadow-box__*"]
  }
}

CLI使用情况

Go二进制支持两种模式：

topo-shadow-box serve 启动MCP服务器（克劳德代码插件模式）。
topo-shadow-box [flags] 运行一次CLI生成并写入输出文件。

构建二进制文件

cd go
go build -o /usr/local/bin/topo-shadow-box ./cmd/topo-shadow-box

快速入门示例

# Circle area -> 3MF
topo-shadow-box --lat 35.99 --lon -78.90 --radius 5000 --output durham.3mf

# Bounding box -> OpenSCAD
topo-shadow-box --north 36.1 --south 35.9 --east -78.8 --west -79.0 --output area.scad

# GPX track area -> SVG
topo-shadow-box --gpx /path/to/ride.gpx --output ride.svg

# Custom model options + subset of map features
topo-shadow-box \
  --lat 35.99 --lon -78.90 --radius 5000 \
  --output model.3mf \
  --width 150 \
  --vertical-scale 2.0 \
  --base-height 8 \
  --shape circle \
  --resolution 250 \
  --features roads,water \
  --color-terrain "#8B7355" \
  --color-water "#4A90D9"

CLI标志参考

标志	默认值	描述
`--lat`, `--lon`, `--radius`	--	圆形区域输入(`radius` （单位：米）
`--north`, `--south`, `--east`, `--west`	--	显式边界框输入
`--gpx`	--	GPX文件路径（使用GPX边界+默认填充）
`--output`, `-o`	——	输出路径；扩展名选择格式(`.3mf`, `.scad`, `.svg`)
`--width`	`200`	模型宽度（mm）
`--vertical-scale`	`1.5`	高程夸大倍数
`--base-height`	`10`	固体基底厚度（mm）
`--shape`	`square`	`square`, `circle`, `hexagon`, `rectangle`
`--resolution`	`200`	每个轴的高程网格分辨率
`--features`	`roads,water,buildings`	CSV功能列表；使用空字符串跳过功能
`--color-terrain`	`#C8A882`	地形颜色
`--color-roads`	`#D4C5A9`	道路颜色
`--color-water`	`#4682B4`	水的颜色
`--color-buildings`	`#E8D5B7`	建筑物颜色
`--color-gpx-track`	`#FF0000`	GPX轨迹颜色

验证规则

只需要一种输入模式：
- --lat + --lon + --radius
- --north + --south + --east + --west
- --gpx
--output 是必需的。
--shape 必须是以下之一 square, circle, hexagon, rectangle.
颜色必须 #RRGGBB.
输出格式根据文件扩展名推断。

作为MCP服务器运行

topo-shadow-box serve

CLI故障排除

error: --output is required
- 添加 --output <path> （或 -o <path>).扩展必须是 .3mf, .scad，或 .svg.
one of --lat/--lon/--radius, --north/--south/--east/--west, or --gpx is required
- 只提供一种输入模式。不要混合坐标/bbox/GPX输入。
--lat/--lon/--radius ... are mutually exclusive （或bbox/GPX等效物）
- 删除额外的输入标志，以便只使用一种区域定义方法。
cannot infer output format from extension ...
- 使用支持的输出扩展： .3mf, .scad，或 .svg.
invalid --shape ...
- 使用以下选项之一： square, circle, hexagon, rectangle.
颜色格式错误(must be in #RRGGBB format)
- 使用带前导的6位十六进制 #例如。 #C8A882.
在标高或特征步骤期间网络/数据获取失败
- 重试命令（瞬态网络问题很常见）。
- 尝试更小或更低的面积 --resolution 如果请求超时。
- 对于仅功能故障，您仍然可以通过设置生成地形 --features ''.
GPX错误(open gpx...、解析失败或无边界）
- 验证文件是否存在，以及是否为带有跟踪点的有效GPX XML。
- 请尝试从源应用程序/设备再次导出GPX。
预览工具报告未生成网格（MCP模式）
- 跑 generate_model 先打电话 preview.

代理对话示例

这些演示了如何提示Claude（或任何支持MCP的代理）生成阴影框。代理会自动调用工具——你只需描述你想要什么。

示例1：坐标中的阴影框

用户：

为我制作一个北卡罗来纳州阿什维尔市中心的3D打印阴影盒。六边形，宽150毫米。将其保存到我的桌面。

代理人：

⏺ set_area_from_coordinates(lat=35.5951, lon=-82.5515, radius_m=2000)
  ↳ Area set: 35.545°N–35.645°N, 82.596°W–82.507°W (≈4.0×4.0 km)

⏺ validate_area()
  ↳ OK — area 16.0 km², elevation relief 312 m

⏺ fetch_elevation(resolution=200)
  ↳ Elevation grid fetched: 200×200 (40 000 points), range 606–918 m

⏺ fetch_features()
  ↳ Fetched 87 roads, 12 water bodies, 43 buildings from OpenStreetMap

⏺ set_model_params(width_mm=150, shape="hexagon", vertical_scale=1.5)
  ↳ Model params updated

⏺ generate_model()
  ↳ Terrain mesh … roads … water … buildings … frame — done (6 meshes)

⏺ export_3mf(output_path="/Users/you/Desktop/asheville.3mf")
  ↳ Exported 6-material 3MF to /Users/you/Desktop/asheville.3mf (4.2 MB)

代理人回复：

完成！ asheville.3mf 位于您的桌面上。它有六个材料槽：地形、道路、水、建筑物、框架和基础。在PrusaSlicer或Bambu Studio中打开它，并为每个插槽指定灯丝颜色。

示例2:GPX轨迹中的阴影框

用户：

我有一份早上骑行的GPX文件 /Users/you/rides/morning_ride.gpx。生成一个阴影框，显示路线及其下方的地形。圆形。导出到 /tmp/ride.3mf.

代理人：

⏺ set_area_from_gpx(file_path="/Users/you/rides/morning_ride.gpx", padding_m=500)
  ↳ GPX loaded: 1 track, 2 043 points. Area set with 500 m padding.

⏺ validate_area()
  ↳ OK — area 28.4 km², elevation relief 487 m

⏺ fetch_elevation(resolution=200)
  ↳ Elevation grid fetched: 200×200, range 312–799 m

⏺ fetch_features(include=["roads", "water"])
  ↳ Fetched 134 roads, 8 water bodies

⏺ set_model_params(shape="circle", vertical_scale=2.0)
  ↳ Model params updated

⏺ generate_model()
  ↳ Terrain mesh … roads … water … GPX track strip … frame — done (5 meshes)

⏺ export_3mf(output_path="/tmp/ride.3mf")
  ↳ Exported 5-material 3MF to /tmp/ride.3mf (5.8 MB)

代理人回复：

您的骑乘影子箱位于 /tmp/ride.3mf。GPX轨迹是它自己的材质对象，因此您可以用对比色打印它。圆形足迹将地形和道路清晰地剪裁到边界。

工具参考

看 docs/tool-reference.md 获取完整的工具参考、典型的工作流程、输出格式和数据源。

发展

看 docs/development.md.

许可证

看许可证.

使用说明

地形阴影框

特性

安装

添加到克劳德代码

添加到Codex

权限

CLI使用情况

构建二进制文件

快速入门示例

CLI标志参考

验证规则

作为MCP服务器运行

CLI故障排除

代理对话示例

示例1：坐标中的阴影框

示例2:GPX轨迹中的阴影框

工具参考

发展

许可证

相关 MCP

3D打印控制服务器

OpenSCAD 3D模型生成服务

Bambu 3D打印机控制 MCP 服务器

Klipper打印机管理服务

3D打印自动化服务器

3D打印网格处理服务器