Transloadit で位置情報を画像に透かしとして追加するツールの作成

写真には、EXIF メタデータとして GPS 座標が含まれている場合があります。この座標をローカルで読み取り、逆ジオコーダーに地名を問い合わせてから、Transloadit でその地名を画像に追加できます。EXIF の読み取りと逆ジオコーディングは別の処理です。ジオコーダーが画像のメタデータを抽出するわけではありません。

始める前に
Node.js 24 以降と、GPS メタデータを含む、ご自身が所有する JPEG を使用してください。このサンプルは、すべてのカメラ RAW 形式や HEIC の派生形式への対応を保証するものではありません。実際に使用するライブラリをインストールします。
npm install exifr@7.1.3 @transloadit/node@4.12.0
生成されたロックファイルはプロジェクトとともに保存してください。このコードは写真一枚を処理する CLI であり、公開サービスではありません。公開 Nominatim サービスに座標を送信し、Transloadit に写真をアップロードします。機密性の高い位置情報、使用許可のない写真、自動化された大量処理には使用しないでください。
Nominatim の利用ポリシーをお読みください。利用者を識別できる連絡先を指定し、同時に実行するインスタンスは一つだけにしてください。検索の間隔を少なくとも一秒空け、同じ写真を繰り返し問い合わせずに以前の結果を再利用してください。製品やバッチパイプラインでは、その処理量を契約上許容するプロバイダーを選ぶか、独自のジオコーダーをホストしてください。
コード
次のプログラム全体を geo-watermarker.mjs に保存してください。TRANSLOADIT_AUTH_KEY、TRANSLOADIT_AUTH_SECRET、GEOCODER_CONTACT、PHOTO はローカル環境の環境変数で指定します。GEOCODER_CONTACT には、秘密情報ではなく、アプリケーション運用者に実際に連絡できるメールアドレスを指定してください。
import { open } from 'node:fs/promises'
import { setTimeout as delay } from 'node:timers/promises'
import { Transloadit } from '@transloadit/node'
import exifr from 'exifr'
function required(name) {
const value = process.env[name]
if (!value) throw new Error('Missing configuration.')
return value
}
async function readPhoto(path) {
const handle = await open(path, 'r')
try {
const stat = await handle.stat()
if (!stat.isFile() || stat.size === 0 || stat.size > 8 * 1024 * 1024) {
throw new Error('Use a JPEG no larger than 8 MiB.')
}
const bytes = Buffer.alloc(stat.size)
let offset = 0
while (offset < bytes.length) {
const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, null)
if (bytesRead === 0) throw new Error('Photo changed while reading.')
offset += bytesRead
}
if (bytes[0] !== 0xff || bytes[1] !== 0xd8) throw new Error('Use a JPEG photo.')
return bytes
} finally {
await handle.close()
}
}
async function placeFor(latitude, longitude, contact) {
if (!Number.isFinite(latitude) || !Number.isFinite(longitude) ||
Math.abs(latitude) > 90 || Math.abs(longitude) > 180) {
throw new Error('Photo has no valid GPS coordinates.')
}
const url = new URL('https://nominatim.openstreetmap.org/reverse')
url.searchParams.set('format', 'jsonv2')
url.searchParams.set('lat', String(latitude))
url.searchParams.set('lon', String(longitude))
url.searchParams.set('zoom', '10')
url.searchParams.set('accept-language', 'en')
await delay(1000)
const response = await fetch(url, {
headers: { 'User-Agent': 'PhotoWatermarker/1.0 (' + contact + ')' },
signal: AbortSignal.timeout(10_000),
})
if (!response.ok) throw new Error('Location lookup failed.')
const data = await response.json()
if (typeof data?.display_name !== 'string') throw new Error('No place was found.')
// Keep the label bounded and plain text before sending it to the image renderer.
const label = data.display_name.replace(/[\u0000-\u001f\u007f]/g, ' ').trim()
if (!label || label.length > 160) throw new Error('Place label needs manual review.')
return label
}
async function main() {
const photo = required('PHOTO')
const authKey = required('TRANSLOADIT_AUTH_KEY')
const authSecret = required('TRANSLOADIT_AUTH_SECRET')
const contact = required('GEOCODER_CONTACT')
if (!/^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/.test(contact)) {
throw new Error('Provide a contact email for the geocoder.')
}
const bytes = await readPhoto(photo)
const gps = await exifr.gps(bytes)
const address = await placeFor(gps?.latitude, gps?.longitude, contact)
const transloadit = new Transloadit({ authKey, authSecret })
const result = await transloadit.createAssembly({
waitForCompletion: true,
timeout: 120_000,
signal: AbortSignal.timeout(120_000),
uploads: { photo: bytes },
params: {
fields: { address },
steps: {
':original': { robot: '/upload/handle' },
watermarked: {
robot: '/image/resize',
use: ':original',
result: true,
format: 'jpg',
strip: true,
text: [{
text: '${fields.address}',
size: 24,
font: 'Ubuntu',
color: '#ffffff',
background_color: '#000000',
align: 'center',
valign: 'bottom',
y_offset: -12,
}],
imagemagick_stack: 'v3.0.2',
},
},
},
})
const output = result.results?.watermarked?.[0]?.ssl_url
if (result.ok !== 'ASSEMBLY_COMPLETED' || typeof output !== 'string') {
throw new Error('No completed watermarked image was returned.')
}
const url = new URL(output)
if (url.protocol !== 'https:') throw new Error('Unexpected result URL.')
console.log('Result: ' + url.href)
console.log('Place data: OpenStreetMap contributors, https://www.openstreetmap.org/copyright')
}
main().catch(() => {
console.error('Watermarking failed. Check configuration, photo metadata and service availability.')
process.exitCode = 1
})
情報の抽出
Exifr は JPEG の GPS タグを読み取り、緯度と経度を十進数に変換します。ゼロも有効な座標なので、このプログラムでは真偽値としての評価ではなく、数値の範囲を検証します。座標がなければ、アップロードを行う前に処理を停止します。
サイズを制限したバッファーをメタデータの抽出とアップロードの両方に使用することで、内容が変更されている可能性のあるファイルを再度読み込まずに済みます。読み取り中はローカルの写真を変更しないでください。
逆ジオコーディング
逆ジオコーディングは、座標を地図上の近隣の場所と関連付ける処理であり、写真の撮影場所を証明するものではありません。EXIF は存在しない場合も、編集されている場合も、不正確な場合もあります。このサンプルでは大まかな地名を要求しますが、元の座標はそのままプロバイダーに送信します。
CLI は OpenStreetMap の帰属表示を出力します。取得した地名データを公開する際は、公開先のどこでも必要な帰属表示とライセンス表示を維持してください。ターミナルのメッセージだけでは、公開された画像ギャラリーの帰属表示にはなりません。実際の写真にこの処理パターンを適用する前に、返された地名を確認し、必要に応じてご自身で短くしてください。
最終結果のエンコード
Auth Key と Auth Secret は、サーバー側の SDK の認証に使用します。ストレージ用の Template 認証情報ではありません。秘密情報をブラウザーのコード、公開リポジトリ、共有するターミナルの記録に決して含めないでください。
/image/resize の Robot は、住所を Assembly Variable として使用し、JPEG を一つ返します。strip オプションは出力から元のメタデータを削除しますが、アップロードした元画像とジオコーダーへのリクエストによって、位置情報はすでにそれぞれのサービスに渡っています。プログラムを実行する前に、データの取り扱い要件を確認してください。
結果
環境を設定したら、次を実行します。
node geo-watermarker.mjs
Assembly が成功すると、一時的な結果 URL と帰属表示が出力されます。結果は速やかにダウンロードするか、管理下にあるストレージへのエクスポート用 Step を追加してください。画像の寸法によって地名の表示が切れていないか確認してください。固定のフォントサイズはあくまで一例であり、あらゆる画像に適したレイアウトではありません。

この例では、ローカルでのメタデータ抽出、明示的な位置情報の検索、マネージドサービスによる透かしの追加という連携の境界を示しています。製品向けに自動化するには、同意の取得、適切なプロバイダーの利用規約、検索結果の保存、運用上の制限、レビュー済みの公開ワークフローも必要です。