GeoIntel

GeoIntel 是一款基于 Python 的工具，利用 Google 的 Gemini API，通过人工智能驱动的地理定位分析，揭示照片的拍摄地点。

安装

# 基本安装
pip install geointel

使用方法

Web 界面（全新！）

启动具有现代 UI 的交互式 Web 界面：

- 标准：
$ geointel --web

- 自定义主机和端口：
$ geointel --web --host 0.0.0.0 --port 4000 

然后在浏览器中打开 http://127.0.0.1:5000。

功能：

• 拖放上传图片
• 浏览器内 API 密钥配置
• 交互式 3D Google 地图
• 实时 AI 分析及详细解释

命令行界面

geointel --image path/to/your/image.jpg

可用参数

参数 描述

--web	启动 Web 界面（无需 --image）
--host	Web 界面的主机地址（默认：127.0.0.1）
--port	Web 界面的端口号（默认：5000）
--image	CLI 模式下必填。待分析图像文件路径或 URL
--context	关于图像的附加上下文信息
--guess	您对图像拍摄地点的猜测
--output	保存结果的输出文件路径（JSON 格式）
--api-key	自定义 Gemini API 密钥

示例

启动 Web 界面：
$ geointel --web

基本 CLI 使用：
$ geointel --image vacation_photo.jpg

添加额外上下文：
$ geointel --image vacation_photo.jpg --context "2023 年暑假期间拍摄"

提供位置猜测：
$ geointel --image vacation_photo.jpg --guess "地中海沿岸"

将结果保存到文件：
$ geointel --image vacation_photo.jpg --output results.json

使用自定义 API 密钥：
$ geointel --image vacation_photo.jpg --api-key "your-api-key-here"

API 密钥设置

GeoIntel 使用 Google 的 Gemini API。您可以：

- 将 API 密钥设置为环境变量：GEMINI_API_KEY=your_key_here

- 在命令行中使用 --api-key 参数

请从 Google AI Studio 获取您的 Gemini API 密钥。

SDK

from geointel import GeoIntel

# 初始化 GeoIntel
geointel = GeoIntel()

# 分析一张图片并获取 JSON 结果
result = geointel.locate(image_path="image.jpg")

# 处理 JSON 数据
if "error" in result:
    print(f"错误：{result['error']}")
else:
    # 访问第一个位置
    if "locations" in result 和 result["locations"]:
        location = result["locations"][0]
        print(f"位置：{location['city']}, {location['country']}")
        
        # 获取 Google 地图链接
        if "coordinates" in location：
            lat = location["coordinates"]["latitude"]
            lng = location["coordinates"]["longitude"]
            maps_url = f"https://www.google.com/maps?q={lat},{lng}"

特性

• 利用 Google 的 Gemini API 进行图像的 AI 驱动地理定位

• 根据图像坐标生成 Google 地图链接

• 提供位置预测的置信度等级

• 支持附加上下文和位置猜测

• 可将结果导出为 JSON

• 同时支持本地图像文件和图像 URL

响应格式

• API 返回结构化的 JSON 响应，包含：

• interpretation：对图像的全面分析

• locations：可能位置数组，包含：

• 国家、州和城市信息

• 置信度级别（高/中/低）

• 坐标（纬度/经度）

• 推理的详细说明

免责声明：

GeoIntel 仅用于教育和研究目的。尽管它使用 AI 模型来估算图像的拍摄地点，但其预测并不保证准确。请勿将此工具用于监视、跟踪、执法或其他可能侵犯个人隐私、违反法律或造成伤害的活动。

作者和贡献者对因使用或误用本软件而导致的任何损害、法律问题或后果不承担任何责任。请自行评估风险并谨慎使用。

在使用基于 AI 的工具时，请始终遵守当地、国家和国际法律法规。

贡献

1. 克隆仓库

2. 创建新分支（git checkout -b feature/new-feature）。

3. 提交更改（git commit -am '添加新功能'）。

4. 推送到分支（git push origin feature/new-feature）。

5. 发起拉取请求。

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

GeoIntel 快速上手指南

GeoIntel 是一款基于 Google Gemini API 的 Python 工具，利用 AI 技术分析图片内容，推断拍摄地点并生成详细的地理位置报告。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Windows、macOS 或 Linux
• Python 版本：Python 3.8 或更高版本
• API 密钥：需要拥有 Google Gemini API Key
  • 获取地址：Google AI Studio
  • 配置方式（任选其一）：
    1. 设置环境变量：export GEMINI_API_KEY=your_key_here (Linux/macOS) 或 set GEMINI_API_KEY=your_key_here (Windows)
    2. 在使用时通过 --api-key 参数传入

安装步骤

使用 pip 进行基础安装：

pip install geointel

提示：国内用户若下载缓慢，可使用清华或阿里镜像源加速安装：

pip install geointel -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

GeoIntel 提供命令行（CLI）和 Web 界面两种使用方式。

方式一：命令行快速分析

最直接的使用方式是传入图片路径进行分析：

geointel --image path/to/your/image.jpg

进阶用法示例：

• 添加背景信息辅助判断：

  geointel --image vacation_photo.jpg --context "Taken during summer vacation in 2023"
  

• 提供猜测地点以缩小范围：

  geointel --image vacation_photo.jpg --guess "Mediterranean coast"
  

• 将结果保存为 JSON 文件：

  geointel --image vacation_photo.jpg --output results.json
  

• 临时指定 API Key：

  geointel --image vacation_photo.jpg --api-key "your-api-key-here"
  

方式二：Web 交互界面

启动带有现代化 UI 的网页版，支持拖拽上传和 3D 地图展示：

geointel --web

启动后，在浏览器中访问 http://127.0.0.1:5000 即可使用。

如需自定义监听地址和端口：

geointel --web --host 0.0.0.0 --port 4000

方式三：Python SDK 集成

在代码中直接调用 GeoIntel 进行开发：

from geointel import GeoIntel

# 初始化 GeoIntel
geointel = GeoIntel()

# 分析图片并获取 JSON 结果
result = geointel.locate(image_path="image.jpg")

# 处理结果
if "error" in result:
    print(f"Error: {result['error']}")
else:
    if "locations" in result and result["locations"]:
        location = result["locations"][0]
        print(f"Location: {location['city']}, {location['country']}")
        
        # 生成 Google Maps 链接
        if "coordinates" in location:
            lat = location["coordinates"]["latitude"]
            lng = location["coordinates"]["longitude"]
            maps_url = f"https://www.google.com/maps?q={lat},{lng}"
            print(f"Map URL: {maps_url}")

---

免责声明：本工具仅供教育和研究用途。预测结果不保证绝对准确，严禁用于监控、人肉搜索、执法或其他侵犯隐私及违法的活动。使用者需自行承担风险并遵守相关法律法规。