地形阴影框
生成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 serveCLI故障排除
error: --output is required
- 添加 --output （或 -o ).扩展必须是 .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 获取完整的工具参考、典型的工作流程、输出格式和数据源。
发展
许可证
看 许可证.