設定ガイド (Configuration Guide)
バージョン: v3.11.1
Copyright (c) 2026 Masanori Sakai
Licensed under the MIT License
概要
このガイドでは、流星検出システムの各種設定方法とチューニング手法について説明します。
サンプル画面
全カメラ設定ページの例です。
目次
- カメラ命名規則（v3.11.0+）
- 環境変数
- SQLite 検出データベース（v3.6.0+）
- マスク設定（固定カメラ向け）
- ノイズ帯マスク設定（v1.12.0+）
- 検出パラメータ
- 感度プリセット
- 処理スケール設定
- 天文薄暮時間帯設定
- 薄明動作モード（v3.5.0+）
- ハードウェア別推奨設定
- チューニング方法
- バージョン別新機能
カメラ命名規則（v3.11.0+）
v3.11.0 以降、generate_compose.py はカメラの内部名（CAMERA{i}_NAME）を インデックスベースで固定 します。生成される内部名は camera1 / camera2 / camera3 ... のみで、IP アドレスを含みません。
本ドキュメントでは用語を以下の 2 種類に統一します（UI 側の表記揺れを避けるため）。
- 内部名（
CAMERA_NAME/CAMERA{i}_NAME）: ディレクトリ名・SQLite のcamera列・runtime_settings/<name>.jsonのファイル名に使用。camera1/camera2... で固定。 - 表示名（
CAMERA_NAME_DISPLAY/CAMERA{i}_NAME_DISPLAY）: ダッシュボード UI のラベルにのみ使用。未設定時は内部名と同じ値が UI に出る。
背景
v3.10.x までは内部名に IP が含まれていました（例: camera1_10_0_1_25）。この方式には以下の課題がありました:
- カメラの IP を変更すると内部名も変わり、過去の検出結果ディレクトリと紐づかなくなる
- SQLite の
camera列にも旧名が残り続け、統計やフィルタが分断される
仕様
CAMERA{i}_NAME = camera{i}で常に固定される。streamersファイルの 3 列目は表示名としてのみ扱われ、内部名には使われず、ダッシュボード UI の表示名 (CAMERA{i}_NAME_DISPLAY) にのみ反映される- 保存先ディレクトリは
$DETECTIONS_DIR/camera{i}/、runtime_settings/camera{i}.jsonなども同じ内部名で統一される CAMERA_NAME_DISPLAYはあくまで表示名であり、ファイル名やディレクトリ名には使われない
旧環境からの移行
旧 IP ベースのディレクトリ（camera1_10_0_1_25/ など）が既にある場合は、スタンドアロンスクリプト migrate_camera_dirs.py で安全に移行できます。
# 実行前に必ず dry-run で内容確認
python migrate_camera_dirs.py --dry-run
# 問題なければ本実行（対話確認あり）
python migrate_camera_dirs.py
# 対話確認を省略する場合
python migrate_camera_dirs.py --yes
主な動作:
detections/camera{i}_*/配下のメディア（.mp4/.jpg/.png）をdetections/camera{i}/へ移動detections.jsonlは追記マージdetections.dbのcamera列と各パスカラムを新名に一括 UPDATE（実行前に.bak_<timestamp>バックアップを自動作成）- 元の
camera{i}_*/はcamera{i}_*.migrated_<timestamp>/へリネームして残置
詳細手順は OPERATIONS_GUIDE.md の「v3.11.0 → カメラ名インデックス化アップデート」節を参照してください。
環境変数
カメラコンテナの環境変数
docker-compose.ymlで設定される環境変数:
| 変数名 | デフォルト値 | 説明 | 設定例 |
|---|---|---|---|
TZ |
Asia/Tokyo |
タイムゾーン | America/New_York |
RTSP_URL |
- | RTSPストリームURL | rtsp://user:pass@192.0.2.25/live |
CAMERA_NAME |
camera |
カメラの内部名（v3.11.0+ では generate_compose.py によって camera{i} に固定設定される） |
camera1 |
CAMERA_NAME_DISPLAY |
"" |
カメラの表示名（ダッシュボード UI のみで使用、ディレクトリ名には使われない） | 東側 |
SENSITIVITY |
medium |
検出感度 | low / medium / high / faint / fireball |
SCALE |
0.5 |
処理スケール | 0.25 ~ 1.0 |
BUFFER |
15 |
リングバッファ秒数（RTSP Webは検出前後1秒+最大検出時間に上限調整） | 10 ~ 30 |
EXCLUDE_BOTTOM |
0.0625 |
画面下部除外率 | 0.0 ~ 0.25 |
EXTRACT_CLIPS |
true |
クリップ動画保存 | true / false |
LATITUDE |
35.3606 |
観測地の緯度 | 35.6762（東京） |
LONGITUDE |
138.7274 |
観測地の経度 | 139.6503（東京） |
TIMEZONE |
Asia/Tokyo |
タイムゾーン名 | UTC / Europe/London |
ENABLE_TIME_WINDOW |
true |
天文薄暮時間帯制限 | true / false |
WEB_PORT |
8080 |
内部HTTPポート | 通常変更不要 |
MASK_IMAGE |
"" |
事前生成済みマスク画像（優先） | /app/mask_image.png |
MASK_FROM_DAY |
"" |
昼間画像からマスク生成 | /app/mask_from_day.jpg |
MASK_DILATE |
20 |
マスク拡張ピクセル数 | 10 / 30 |
MASK_SAVE |
"" |
マスク保存先 | /output/masks/camera1_mask.png |
NUISANCE_MASK_IMAGE |
"" |
ノイズ帯マスク画像（v1.12.0+） | /app/nuisance_mask.png |
NUISANCE_FROM_NIGHT |
"" |
夜間画像からノイズ帯マスク生成（v1.12.0+） | /app/nuisance_night.jpg |
NUISANCE_DILATE |
3 |
ノイズ帯マスク拡張ピクセル数（v1.12.0+） | 2 / 5 |
NUISANCE_OVERLAP_THRESHOLD |
0.3 |
ノイズ帯重複率閾値（v1.12.0+） | 0.2 ~ 0.5 |
EXCLUDE_EDGE_RATIO |
0.0 |
画面四辺除外率（v1.16.0+） | 0.0 ~ 0.2 |
TWILIGHT_DETECTION_MODE |
reduce |
薄明時の検出動作（v3.5.0+） | reduce（感度を下げて継続）/ skip（停止） |
TWILIGHT_TYPE |
nautical |
薄明の種類・太陽沈み角（v3.5.0+） | civil(6°) / nautical(12°) / astronomical(18°) |
TWILIGHT_SENSITIVITY |
low |
reduce モード時の感度プリセット（v3.5.0+） |
low / medium / high / faint |
TWILIGHT_MIN_SPEED |
200 |
reduce モード時の最小速度 px/秒（v3.5.0+）。鳥など遅い物体の誤認識を抑制 |
100 ~ 500 |
TWILIGHT_BIRD_FILTER_ENABLED |
true |
薄明時の黒点フィルタ（鳥シルエット除外） | true / false |
TWILIGHT_BIRD_MIN_BRIGHTNESS |
80 |
薄明時の除外輝度閾値（0-255、これ未満を除外） | 40 ~ 120 |
BIRD_FILTER_ENABLED |
false |
通常時の黒点フィルタ（opt-in） | true / false |
BIRD_MIN_BRIGHTNESS |
80 |
通常時の除外輝度閾値 | 40 ~ 120 |
!!! warning "高閾値のリスク"
BIRD_MIN_BRIGHTNESS および TWILIGHT_BIRD_MIN_BRIGHTNESS を 120 以上に設定すると暗い流星を誤除外するリスクがある。faint プリセット使用時は特に注意。
ダッシュボードの環境変数
| 変数名 | デフォルト値 | 説明 |
|---|---|---|
PORT |
8080 |
HTTPサーバーポート |
LATITUDE |
35.3606 |
観測地の緯度 |
LONGITUDE |
138.7274 |
観測地の経度 |
TIMEZONE |
Asia/Tokyo |
タイムゾーン名 |
ENABLE_TIME_WINDOW |
false |
天文薄暮時間帯制限（カメラコンテナ側のデフォルトは true） |
CAMERA1_NAME |
- | カメラ1の内部名（ディレクトリ名・SQLite の camera 列に使われる） |
CAMERA1_NAME_DISPLAY |
- | カメラ1の表示名（ダッシュボード UI 専用。保存先ディレクトリや runtime_settings のファイル名には使われない） |
CAMERA1_URL |
- | カメラ1のURL |
CAMERA1_STREAM_KIND |
webrtc |
ライブ表示方式 (mjpeg / webrtc) |
CAMERA1_STREAM_URL |
CAMERA1_URL |
ライブ表示用URL (webrtc 時は http://localhost:1984/stream.html?src=camera1&mode=webrtc&mode=mse... など。埋め込み時はダッシュボード表示中のホスト名を優先して接続) |
DETECTIONS_DIR |
/output |
検出結果ディレクトリ |
CAMERA1_YOUTUBE_KEY |
- | カメラ1のYouTubeストリームキー（設定時のみYouTube配信ボタン表示） |
CAMERA1_RTSP_URL |
- | カメラ1のRTSP URL（YouTube配信用。ffmpegでAAC変換に使用） |
GO2RTC_API_URL |
http://localhost:1984 |
go2rtc APIのURL（Docker内では自動的に http://go2rtc:1984 に変換） |
CAMERA_MONITOR_ENABLED |
true |
カメラ監視有効化 |
CAMERA_MONITOR_INTERVAL |
2.0 |
カメラ監視間隔（秒） |
CAMERA_MONITOR_TIMEOUT |
6.0 |
監視タイムアウト（秒） |
CAMERA_RESTART_TIMEOUT |
5.0 |
再起動リクエストのタイムアウト（秒） |
CAMERA_RESTART_COOLDOWN_SEC |
120 |
再起動クールダウン（秒） |
CAMERA_MONITOR_FAIL_THRESHOLD |
12 |
監視失敗閾値（連続N回失敗で再起動） |
DETECTION_MONITOR_INTERVAL |
2.0 |
検出結果ファイル監視間隔（秒） |
環境変数の設定方法
方法1: generate_compose.pyで一括設定
python generate_compose.py \
--streamers streamers \
--sensitivity high \
--scale 0.5 \
--buffer 15 \
--streaming-mode webrtc \
--latitude 35.6762 \
--longitude 139.6503 \
--enable-time-window true \
--extract-clips true \
--mask-output-dir masks
方法2: docker-compose.ymlを直接編集
services:
camera1:
environment:
- SENSITIVITY=high
- SCALE=0.5
- EXTRACT_CLIPS=false
dashboard:
environment:
- CAMERA1_STREAM_KIND=webrtc
- CAMERA1_STREAM_URL=http://localhost:1984/stream.html?src=camera1&mode=webrtc&mode=mse&mode=hls&mode=mjpeg&background=false
webrtc を Docker 内の go2rtc で使う場合は、go2rtc.yaml の webrtc.candidates にブラウザから到達可能なホスト側 IP/ポートを設定してください。generate_compose.py は既定でローカル IP を自動検出して設定し、必要な場合だけ --go2rtc-candidate-host <host-ip> で上書きできます。
go2rtc は webrtc.candidates で指定した host candidate に加えて、STUN 由来の srflx candidate を返すことがあります。srflx がログやブラウザ開発者ツールに見えても異常ではありません。重要なのは、同時に指定した host candidate も返っており、最終的な表示モードが RTC になっていることです。
方法3: .envファイルを使用
# .env ファイルを作成
cat > .env << 'EOF'
# 全カメラ共通設定
SENSITIVITY=medium
SCALE=0.5
BUFFER=15
EXTRACT_CLIPS=true
# 観測地点
LATITUDE=35.6762
LONGITUDE=139.6503
ENABLE_TIME_WINDOW=true
# RTSP認証情報（セキュリティ向上）
RTSP_USER=username
RTSP_PASS=password
EOF
chmod 600 .env # パーミッション制限
docker-compose.ymlで参照:
environment:
- SENSITIVITY=${SENSITIVITY:-medium}
- RTSP_URL=rtsp://${RTSP_USER}:${RTSP_PASS}@192.0.2.25/live
ダッシュボード一括設定（再ビルド不要） v1.13.0+
/settings から全カメラへ設定を一括反映できます。
GET /settings: 設定UIGET /camera_settings/current: 現在値取得POST /camera_settings/apply_all: 全カメラ一括反映
反映タイミング
即時反映（再起動不要）:
- 検出パラメータ: diff_threshold, min_brightness, min_linearity, min_length, min_speed, min_duration, max_duration, min_area, max_area
- ノイズ除外パラメータ: nuisance_overlap_threshold, nuisance_path_overlap_threshold, min_track_points, max_stationary_ratio, small_area_threshold
- 録画マージン設定（v1.14.0+）: clip_margin_before, clip_margin_after
- マスク設定: mask_dilate, nuisance_dilate, mask_*, nuisance_* の画像パス
- 画面端除外（v1.16.0+）: exclude_edge_ratio
自動再起動で反映（再ビルド不要）:
- 基本設定: sensitivity, scale, buffer, extract_clips
永続化
起動時依存の設定は output/runtime_settings/<camera>.json に保存されます。
これにより、コンテナ再起動後も同じ設定が維持されます。
<camera> には CAMERA_NAME の内部名が使われ、CAMERA_NAME_DISPLAY の表示名には切り替わりません。
設定変更の推奨手順
- ダッシュボードの
/settingsページにアクセス - 変更したいパラメータを入力（差分のみハイライト表示）
- 「全カメラに適用」ボタンで一括反映
- 即時反映項目はリアルタイムで適用、再起動項目は自動で再起動
output/runtime_settings/<camera>.jsonに永続化され、次回起動時も有効
SQLite 検出データベース（v3.6.0+）
概要
ダッシュボードは $DETECTIONS_DIR/detections.db（SQLite）を検出データの正本として使用する。
検出エンジンは引き続き各カメラの detections.jsonl に追記し、ダッシュボードが増分同期で SQLite へ取り込む。
自動生成
$DETECTIONS_DIR/detections.db はダッシュボード起動時に自動生成される。手動での作成は不要。
初回移行
既存の detections.jsonl を SQLite へ移行するには、初回のみ以下を実行する：
source .venv/bin/activate
python scripts/migrate_jsonl_to_sqlite.py
DETECTIONS_DIR 環境変数が設定されていない場合、カレントディレクトリの detections/ が対象になる。
ロールバック
既存の JSONL ファイルは移行後も削除されない。SQLite を使わない状態に戻す場合は detections.db を削除するだけでよい。
詳細
SQLite スキーマ、JSONL → SQLite 同期アルゴリズム、主要 API（query_detections() / soft_delete / count_asset_references など）の詳細は DETECTION_STORE.md を参照してください。
マスク設定（固定カメラ向け）
streamers ファイルの書式
streamers ファイルでは | 区切りで最大4フィールドを指定できます。
RTSP URL | マスク画像 | 表示名 | youtube:STREAM_KEY
| フィールド | 必須 | 説明 |
|---|---|---|
| RTSP URL | ○ | カメラのRTSP接続URL |
| マスク画像 | - | 除外マスク生成用の昼間画像パス |
| 表示名 | - | ダッシュボード UI の表示名（CAMERA{i}_NAME_DISPLAY にマップされる。内部名には使われない） |
| youtube:KEY | - | YouTube Liveストリームキー（youtube:プレフィックス必須） |
rtsp://user:pass@192.0.2.25/live | camera1.jpg | 東カメラ
rtsp://user:pass@192.0.2.3/live | camera2.jpg | 西カメラ
rtsp://user:pass@192.0.2.11/live || 南カメラ | youtube:xxxx-xxxx-xxxx-xxxx
streamers に昼間画像を指定
streamers で RTSP URL | 昼間画像 の形式にすると、generate_compose.py 実行時に
除外マスクを自動生成してコンテナに同梱します。
- 画像パスは
streamersと同じフォルダ基準（相対パス可） - マスク生成には OpenCV が必要
その場でマスクを更新（永続化）
ダッシュボードの「マスク更新」ボタンで、現在フレームからマスクを再生成できます。
保存先は /output/masks/<camera>_mask.png です。
generate_compose.py 再実行時のマスク保護
generate_compose.py は実行時に masks/.generated_hashes.json へ生成マスクの SHA256 ハッシュを記録します。
次回実行時にハッシュを比較し、手動で更新されたマスクは上書きしません。
| 状況 | 動作 |
|---|---|
| マスクファイルが存在しない | 新規生成する |
| ハッシュ記録がない（初回 or 削除済み） | 上書き生成する |
| ハッシュ一致（前回生成と同じ） | 上書き生成する |
| ハッシュ不一致（手動更新済み） | スキップ（上書きしない） |
強制上書きする場合は --force-overwrite-masks オプションを指定します:
python generate_compose.py --force-overwrite-masks
.generated_hashes.json は git 管理対象にすることを推奨します（「システムが最後に生成したハッシュ」を追跡できるため）。
MASK_BUILD_DIR 環境変数
| 項目 | 内容 |
|---|---|
| 変数名 | MASK_BUILD_DIR |
| 設定主体 | 自動設定（generate_compose.py が docker-compose.yml に埋め込む） |
| 用途 | コンテナ内の masks/ マウントパスを示す。ダッシュボードの「マスク更新」操作時に、コンテナ内の検出用パスへ書き込んだ後、この変数が示すパスにも同期書き込みする |
!!! note "MASK_BUILD_DIR の扱い"
MASK_BUILD_DIR はユーザーが手動設定する変数ではありません。また、.generated_hashes.json が削除または git 管理されていない場合、ハッシュ記録が失われるため generate_compose.py 再実行時に手動更新済みのマスクが上書きされることがあります。
ノイズ帯マスク設定（v1.12.0+）
概要
ノイズ帯マスク機能は、電線や部分照明など、動かない明るい線状物体による誤検出を防ぎます。 通常のマスクと異なり、ノイズ帯と軌跡が重複した場合のみ除外判定を行います。
設定パラメータ
| パラメータ | デフォルト値 | 説明 | 推奨値 |
|---|---|---|---|
nuisance_mask_image |
"" |
事前生成済みノイズ帯マスク | /app/nuisance_mask.png |
nuisance_from_night |
"" |
夜間画像からマスク自動生成 | /app/nuisance_night.jpg |
nuisance_dilate |
3 |
マスク拡張ピクセル数 | 2 ~ 5 |
nuisance_overlap_threshold |
0.3 |
重複率閾値（軌跡の何％がノイズ帯に重なったら除外） | 0.2 ~ 0.5 |
設定方法
方法1: 環境変数で直接指定
environment:
- NUISANCE_FROM_NIGHT=/app/nuisance_night.jpg
- NUISANCE_DILATE=3
- NUISANCE_OVERLAP_THRESHOLD=0.3
方法2: ダッシュボードから設定（v1.13.0+）
/settingsページにアクセスnuisance_overlap_thresholdを調整（0.2 = 20%重複で除外）- 「全カメラに適用」で即時反映
使用例：電線対策
電線が画面中央を横切る場合:
environment:
- NUISANCE_FROM_NIGHT=/app/night_with_wires.jpg
- NUISANCE_DILATE=5 # 電線を太めに認識
- NUISANCE_OVERLAP_THRESHOLD=0.25 # 軌跡の25%以上が電線に重なったら除外
注意事項
- 夜間画像を使用: 電線や照明が明るく写っている夜間画像が必要
- 通常マスクとの併用: 建物など完全除外したい領域は通常マスクを使用
- 重複率の調整: 値を小さくすると除外が厳しく、大きくすると緩くなる
検出パラメータ
物理量に読み替える目安（天文観測者向け）
検出しきい値はコード上 px / px/s ですが、観測上は「何km・何km/sか」が重要です。
ここでは、ATOM Cam 2 の水平画角を 120度、解像度を 1920x1080 として読み替えます。
前提:
- 水平1pxあたり角度: 120 / 1920 = 0.0625度（約 0.0010908 rad）
- 距離 R km に対して
- 見かけ長さ L ≈ R * 角度(rad)
- 見かけ速度 V ≈ R * 角速度(rad/s)
現在の標準しきい値（medium）:
- min_length = 20 px
- min_speed = 50 px/s
距離別の換算目安:
| 想定距離 R | 最小検出長（20px） | 最小見かけ速度（50px/s） |
|---|---|---|
| 100 km | 約 2.18 km | 約 5.45 km/s |
| 200 km | 約 4.36 km | 約 10.91 km/s |
| 300 km | 約 6.55 km | 約 16.36 km/s |
読み方:
- 距離が遠いほど、同じ px でも実距離・実速度は大きくなります
- 低空（低仰角）で見える流星は距離が伸びやすく、300km前後になることがあります
- 運用上は「この設定で拾える最低ライン」を km/km/s で把握しておくと調整しやすくなります
DetectionParams クラス
meteor_detector_rtsp_web.py内で定義されるパラメータ:
@dataclass
class DetectionParams:
diff_threshold: int = 30 # 差分閾値
min_brightness: int = 200 # 最小輝度
min_length: int = 20 # 最小軌跡長 (px)
max_length: int = 5000 # 最大軌跡長 (px)
min_duration: float = 0.1 # 最小継続時間 (秒)
max_duration: float = 10.0 # 最大継続時間 (秒)
min_speed: float = 50.0 # 最小速度 (px/s)
min_linearity: float = 0.7 # 最小直線性 (0-1)
min_area: int = 5 # 最小面積 (px²)
max_area: int = 10000 # 最大面積 (px²)
max_gap_time: float = 0.2 # 最大トラッキング間隔 (秒)
max_distance: float = 80 # 最大移動距離 (px)
exclude_bottom_ratio: float = 1/16 # 画面下部除外率
パラメータの詳細説明
diff_threshold（差分閾値）
説明: フレーム間差分の閾値。この値を超える変化を検出対象とする
影響: - 低い値（15-20）: 小さな変化も検出 → 感度高、誤検出も増加 - 高い値（40-50）: 大きな変化のみ検出 → 感度低、誤検出減少
推奨値: - 明るい環境: 40 - 通常環境: 30 - 暗い環境: 20
調整例:
# コード内で直接変更する場合
params = DetectionParams()
params.diff_threshold = 25 # より敏感に
min_brightness（最小輝度）
説明: 検出対象とする最小の明るさ（0-255）
影響: - 低い値（150-180）: 暗い流星も検出 - 高い値（220-255）: 明るい流星のみ検出
推奨値: - 市街地（光害あり）: 220 - 郊外: 200 - 山間部（光害なし）: 180
min_length / max_length（軌跡長）
説明: 検出する軌跡の長さ範囲（ピクセル）
min_length の影響: - 短い（10-15px）: 短い軌跡も検出 → 誤検出増加 - 長い（30-50px）: 長い軌跡のみ → 見逃し増加
推奨値: - 1920x1080: min=20, max=5000 - 1280x720: min=15, max=3000 - 640x480: min=10, max=2000
min_duration / max_duration（継続時間）
説明: 検出する軌跡の時間範囲（秒）
推奨値: - 通常の流星: min=0.1, max=10.0 - 火球専用: min=0.5, max=20.0
min_speed（最小速度）
説明: 検出する最小移動速度（ピクセル/秒）
影響: - 低い値（20-30）: ゆっくり動く物体も検出 → 航空機を誤検出 - 高い値（70-100）: 速い物体のみ → 流星の見逃しが増える
推奨値: 50 px/s
参考: 流星の典型的な速度は100-500 px/s
min_linearity（最小直線性）
説明: 軌跡の直線度合い（0.0-1.0）。1.0が完全な直線
影響: - 低い値（0.5-0.6）: 曲がった軌跡も検出 - 高い値（0.8-0.9）: ほぼ直線のみ検出
推奨値: 0.7
計算方法: 主成分分析（PCA）による固有値比
exclude_bottom_ratio（画面下部除外率）
説明: 画面下部の除外範囲（0.0-1.0）
用途: 地上の建物や木などの誤検出を防ぐ
推奨値: - 空のみ撮影: 0.0 - 地平線が写る: 0.0625（1/16） - 建物が多い: 0.125（1/8）
例:
画面高さ 1080px × 0.0625 = 下から67.5px を除外
exclude_edge_ratio（画面四辺除外率） v1.16.0+
説明: 画面四辺（上下左右）からの除外割合（0.0-0.2）
用途: 画面端のノイズや歪みによる誤検出を防ぐ
影響: - 0.0（デフォルト）: 除外なし - 0.05: 各辺から5%を除外 - 0.1: 各辺から10%を除外 - 0.2（最大）: 各辺から20%を除外
推奨値: - 通常運用: 0.0 - 画面端ノイズあり: 0.05 - 魚眼レンズ（歪み大）: 0.1
設定方法:
# generate_compose.pyで設定
python generate_compose.py --exclude-edge-ratio 0.05
# docker-compose.ymlで設定
environment:
- EXCLUDE_EDGE_RATIO=0.05
# ダッシュボードから即時反映
# /settings ページで exclude_edge_ratio を設定
例:
画面サイズ 1920x1080、EXCLUDE_EDGE_RATIO=0.05 の場合:
- 左右: 1920 × 0.05 = 96px ずつ除外
- 上下: 1080 × 0.05 = 54px ずつ除外
- 有効領域: 1728 × 972px
注意事項:
- exclude_bottom_ratio と併用可能（下部のみさらに除外）
- 値を大きくしすぎると検出範囲が狭まる
clip_margin_before / clip_margin_after（録画マージン設定） v1.14.0+
説明: 検出イベント前後に追加で録画する時間（秒）
用途: 流星の出現直前・直後の状況も記録
デフォルト値:
- clip_margin_before: 0.0秒
- clip_margin_after: 0.0秒
推奨値:
- 標準運用: before=0.5, after=0.5
- 詳細記録: before=1.0, after=1.0
- ディスク節約: before=0.0, after=0.0
設定方法:
# docker-compose.ymlで設定（v1.14.0以降）
environment:
- CLIP_MARGIN_BEFORE=0.5
- CLIP_MARGIN_AFTER=0.5
# ダッシュボードから即時反映（v1.14.0+）
# /settings ページで clip_margin_before, clip_margin_after を設定
使用例:
検出時間 10:00:05.0 ～ 10:00:07.0（2秒間）の場合:
- margin_before=0.5, margin_after=0.5 設定時
- 録画範囲: 10:00:04.5 ～ 10:00:07.5（3秒間）
メリット: - 流星の出現前の空の状態を確認可能 - 複数の流星が連続した場合も記録 - 検出漏れの前後フレームも保存
注意事項: - BUFFER設定より大きい値は無効 - 値を大きくするとファイルサイズが増加
感度プリセット
プリセット一覧
| プリセット | diff_threshold | min_brightness | 用途 | 誤検出率 |
|---|---|---|---|---|
low |
40 | 220 | 明るい流星のみ | 低 |
medium |
30 | 200 | バランス型（推奨） | 中 |
high |
20 | 180 | 暗い流星も検出 | やや高 |
faint |
16 | 150 | 短く暗い流星の取りこぼし低減 | 高 |
fireball |
15 | 150 | 火球専用 | 高 |
プリセットの適用
# generate_compose.pyで設定
python generate_compose.py --sensitivity high
# または docker-compose.ymlで直接設定
environment:
- SENSITIVITY=high
プリセット別の特徴
low（低感度）
特徴: - 明るい流星のみ検出 - 誤検出が最も少ない - 暗い流星は見逃す
推奨環境: - 市街地（光害が多い） - 満月期 - テスト運用時
検出例: - -3等級以上の明るい流星 - 火球
medium（中感度）★推奨
特徴: - バランスの取れた設定 - 多くの環境で良好な結果 - 誤検出と見逃しのバランスが良い
推奨環境: - 郊外 - 標準的な観測環境 - 長期運用
検出例: - 0等級～-3等級の流星 - 一般的な散在流星 - 流星群の流星
high（高感度）
特徴: - 暗い流星も検出 - 誤検出がやや増える - 見逃しが少ない
推奨環境: - 山間部（光害が少ない） - 新月期 - 流星群極大期
検出例: - +2等級～-5等級の流星 - 微光流星
注意点: - 航空機を誤検出する可能性 - ログ確認が必要
fireball（火球専用）
特徴: - 最も敏感な設定 - 長時間・大きな物体を検出 - 誤検出が多い
推奨環境: - 火球専用観測 - 短期集中観測
検出例: - -4等級以上の火球 - 長時間光る流星
追加設定:
max_duration = 20.0 # 長時間OK
min_speed = 20.0 # ゆっくりでもOK
min_linearity = 0.6 # 多少曲がってもOK
処理スケール設定
SCALE パラメータ
説明: フレームを縮小して処理する比率（0.0-1.0）
影響:
| SCALE | 処理サイズ（1920x1080の場合） | CPU使用率 | メモリ使用量 | 検出精度 |
|---|---|---|---|---|
| 1.0 | 1920x1080（等倍） | 100% | 400MB | 最高 |
| 0.5 | 960x540（推奨） | 30% | 200MB | 高 |
| 0.25 | 480x270 | 15% | 100MB | 中 |
推奨設定
graph TD
Start["ハードウェア性能"]
CheckCPU{"CPUコア数"}
CheckMem{"メモリ容量"}
CheckCamera{"カメラ数"}
Scale100["SCALE=1.0<br/>最高精度"]
Scale050["SCALE=0.5<br/>推奨"]
Scale025["SCALE=0.25<br/>省リソース"]
Start --> CheckCPU
CheckCPU -->|"8コア以上"| Scale100
CheckCPU -->|"4コア"| CheckMem
CheckCPU -->|"2コア以下"| Scale025
CheckMem -->|"16GB以上"| Scale050
CheckMem -->|"8GB以下"| CheckCamera
CheckCamera -->|"1-2台"| Scale050
CheckCamera -->|"3台以上"| Scale025
style Scale050 fill:#dff6e8
スケール別の特徴
SCALE=1.0（等倍処理）
メリット: - 最高精度 - 小さな流星も検出 - 軌跡が正確
デメリット: - CPU使用率が高い（90-100%） - メモリ消費が大きい - 多数カメラには不向き
推奨環境: - 高性能PC（8コア以上、16GB RAM以上） - カメラ1-2台 - 短期観測
SCALE=0.5（推奨）
メリット: - 精度とパフォーマンスのバランスが良い - CPU使用率30-50% - 多数カメラに対応可能
デメリット: - 微小な流星は検出困難
推奨環境: - 標準的PC（4コア、8GB RAM） - カメラ3-5台 - 長期運用
SCALE=0.25（省リソース）
メリット: - 最も軽い - CPU使用率15-20% - 多数カメラ対応
デメリット: - 検出精度が低下 - 小さな流星は見逃す
推奨環境: - 低スペックPC（2コア、4GB RAM） - カメラ6台以上 - 明るい流星のみ検出
天文薄暮時間帯設定
ENABLE_TIME_WINDOW の仕組み
説明: 天文薄暮期間（前日の日没～翌日の日出）のみ検出を有効化
gantt
title 1日の検出スケジュール
dateFormat HH:mm
axisFormat %H:%M
section 検出OFF
日中（検出無効）: done, day, 06:00, 10h
section 検出ON
夜間（検出有効）: active, night1, 16:00, 14h
夜間（検出有効）: active, night2, 00:00, 6h
設定方法
# generate_compose.pyで設定
python generate_compose.py \
--enable-time-window true \
--latitude 35.6762 \
--longitude 139.6503
# docker-compose.ymlで直接設定
environment:
- ENABLE_TIME_WINDOW=true
- LATITUDE=35.6762
- LONGITUDE=139.6503
- TIMEZONE=Asia/Tokyo
座標の取得方法
方法1: Google Mapsで取得
- Google Mapsで観測地点を右クリック
- 表示される座標をコピー
- 例:
35.6762, 139.6503
方法2: コマンドラインで取得
# curlで現在地の座標を取得
curl -s "https://ipapi.co/json/" | jq '.latitude, .longitude'
主要都市の座標
| 都市 | 緯度 | 経度 |
|---|---|---|
| 東京 | 35.6762 | 139.6503 |
| 大阪 | 34.6937 | 135.5023 |
| 札幌 | 43.0642 | 141.3469 |
| 福岡 | 33.5904 | 130.4017 |
| 那覇 | 26.2124 | 127.6809 |
| 富士山頂 | 35.3606 | 138.7274 |
時間帯の確認
# ダッシュボードのAPIで確認
curl "http://localhost:8080/detection_window?lat=35.6762&lon=139.6503" | jq
# レスポンス例
{
"start": "2026-02-01 16:45:23",
"end": "2026-02-02 06:12:45",
"enabled": true,
"latitude": 35.6762,
"longitude": 139.6503
}
薄明動作モード（v3.5.0+）
ENABLE_TIME_WINDOW=true の場合、検出対象の夜間時間帯に加えて、薄明（twilight）期間の検出挙動を個別に制御できます。薄明期間は astro_twilight_utils.py によって太陽の沈み角（civil / nautical / astronomical）別に計算されます（詳細は ASTRO_UTILS.md の astro_twilight_utils.py 節を参照）。
関連環境変数
| 変数名 | デフォルト値 | 説明 |
|---|---|---|
TWILIGHT_DETECTION_MODE |
reduce |
薄明期間中の検出動作。reduce（感度を下げて継続）/ skip（候補除外） |
TWILIGHT_TYPE |
nautical |
薄明の定義。civil(6°) / nautical(12°) / astronomical(18°) |
TWILIGHT_SENSITIVITY |
low |
reduce モード時に適用する感度プリセット |
TWILIGHT_MIN_SPEED |
200 |
reduce モード時の最小速度 (px/s)。鳥や航空機など遅い物体の誤検出抑制 |
モード別の挙動
reduce（推奨）: 薄明期間中のみTWILIGHT_SENSITIVITYプリセットを適用し、min_speedをTWILIGHT_MIN_SPEEDまで引き上げる。明るい物体は通常通り検出されるが、鳥・飛行機など遅く暗めの物体が混入しにくくなるskip: 薄明期間中は全候補を破棄する。誤検出を最も抑える代わりに、薄明直後の明るい流星も取りこぼす
鳥シルエット除外フィルタ
薄明時は空が明るく、鳥が「黒い塊」として差分検出にかかることがあります。これを抑えるため、detection_filters.py の filter_dark_objects() によって 平均輝度が閾値未満のオブジェクトを除外 できます。
| 変数名 | デフォルト値 | 適用タイミング |
|---|---|---|
TWILIGHT_BIRD_FILTER_ENABLED |
true |
薄明期間中のみ有効（opt-out） |
TWILIGHT_BIRD_MIN_BRIGHTNESS |
80 |
薄明時の輝度閾値（これ未満は鳥とみなして除外） |
BIRD_FILTER_ENABLED |
false |
通常夜間時間帯にも適用（opt-in） |
BIRD_MIN_BRIGHTNESS |
80 |
通常時の輝度閾値 |
!!! warning "高閾値のリスク"
閾値 120 以上は暗い流星を誤除外するリスクがあります。faint プリセット使用時は特に注意してください。
設定例
# 薄明時は反応を抑えたい（reduce モード、civil 薄明まで抑制）
environment:
- ENABLE_TIME_WINDOW=true
- TWILIGHT_TYPE=civil
- TWILIGHT_DETECTION_MODE=reduce
- TWILIGHT_SENSITIVITY=low
- TWILIGHT_MIN_SPEED=250
- TWILIGHT_BIRD_FILTER_ENABLED=true
# 薄明中は完全停止する（skip モード）
environment:
- ENABLE_TIME_WINDOW=true
- TWILIGHT_TYPE=nautical
- TWILIGHT_DETECTION_MODE=skip
ハードウェア別推奨設定
低スペックPC（2コア、4GB RAM）
environment:
- SENSITIVITY=medium
- SCALE=0.25
- BUFFER=10
- EXTRACT_CLIPS=false # クリップ動画を保存しない
- ENABLE_TIME_WINDOW=true
カメラ数: 最大2台
標準PC（4コア、8GB RAM）★推奨
environment:
- SENSITIVITY=medium
- SCALE=0.5
- BUFFER=15
- EXTRACT_CLIPS=true
- ENABLE_TIME_WINDOW=true
カメラ数: 3-5台
高性能PC（8コア以上、16GB RAM以上）
environment:
- SENSITIVITY=high
- SCALE=0.75
- BUFFER=20
- EXTRACT_CLIPS=true
- ENABLE_TIME_WINDOW=false # 常時検出
カメラ数: 8台以上
Raspberry Pi 4（4GB）
environment:
- SENSITIVITY=low
- SCALE=0.25
- BUFFER=10
- EXTRACT_CLIPS=false
- ENABLE_TIME_WINDOW=true
カメラ数: 最大1台
注意: 長時間運用時はヒートシンク必須
チューニング方法
ステップ1: ベースライン設定
# 推奨設定で開始
python generate_compose.py \
--sensitivity medium \
--scale 0.5 \
--buffer 15
./meteor-docker.sh start
ステップ2: 誤検出の確認
# 1時間運用後、検出結果を確認
ls -lh ./detections/camera1_*/
# ダッシュボードで確認
open http://localhost:8080/
誤検出の種類: - 航空機（点滅する光、ゆっくり移動） - 昆虫（不規則な動き） - 雲の移動（広範囲、ゆっくり） - 車のヘッドライト（画面下部）
ステップ3: 感度調整
誤検出が多い場合
# 感度を下げる
python generate_compose.py --sensitivity low
# または画面下部除外を増やす
python generate_compose.py --exclude-bottom 0.125
見逃しが多い場合
# 感度を上げる
python generate_compose.py --sensitivity high
# さらに短く暗い流星を拾いたい
python generate_compose.py --sensitivity faint
ステップ4: パフォーマンス調整
# リソース使用率を確認
./meteor-docker.sh status
# CPU使用率が高い（70%以上）
python generate_compose.py --scale 0.25
# メモリ使用量が多い
python generate_compose.py --buffer 10
ステップ5: 長期運用
# 1週間運用後の統計
find ./detections -name "*.mp4" | wc -l
# 誤検出率を計算
# 誤検出率 = 誤検出数 / 総検出数
# 目標: 誤検出率 < 20%
環境別チューニング例
市街地（光害あり）
課題: 街灯、車のライト、建物の照明が多い
推奨設定:
environment:
- SENSITIVITY=low
- SCALE=0.5
- EXCLUDE_BOTTOM=0.125 # 下部1/8を除外
- ENABLE_TIME_WINDOW=true
params調整:
params.min_brightness = 220 # 明るい流星のみ
params.min_speed = 70 # 遅い物体を除外
郊外（標準環境）
推奨設定:
environment:
- SENSITIVITY=medium
- SCALE=0.5
- EXCLUDE_BOTTOM=0.0625
- ENABLE_TIME_WINDOW=true
そのままでOK
山間部（光害なし）
課題: 暗い流星も検出したい
推奨設定:
environment:
- SENSITIVITY=faint
- SCALE=0.75
- EXCLUDE_BOTTOM=0.0
- ENABLE_TIME_WINDOW=true
params調整:
params.min_brightness = 150
params.diff_threshold = 16
params.min_area = 5
params.max_distance = 90
トラブルシューティング
検出数が少なすぎる
原因: - 感度が低すぎる - 時間帯設定の問題
対策:
# 感度を上げる
python generate_compose.py --sensitivity high
# さらに取りこぼしを減らす
python generate_compose.py --sensitivity faint
# 時間帯制限を無効化
python generate_compose.py --enable-time-window false
誤検出が多すぎる
原因: - 感度が高すぎる - 航空機や昆虫を検出
対策:
# 感度を下げる
python generate_compose.py --sensitivity low
# 画面下部を除外
python generate_compose.py --exclude-bottom 0.125
CPUが高い
対策:
# 処理スケールを下げる
python generate_compose.py --scale 0.25
# カメラ数を減らす
# streamersファイルから一部削除
ディスク容量が足りない
対策:
# クリップ動画保存を無効化
# docker-compose.ymlで EXTRACT_CLIPS=false
# バッファを減らす
python generate_compose.py --buffer 10
# 古いファイルを削除
./meteor-docker.sh clean
バージョン別新機能
v3.4.6 - 全選択UI常時表示・Dockerfile.dashboard改善
変更点:
- 検出結果一覧の全選択UIを常時表示化（選択モードトグル廃止）。日付選択直後からチェックボックス・「全選択/全解除」・「選択した N 件を削除」ボタンが利用可能。
- Dockerfile.dashboard の apt インストールを BuildKit cache mount 方式に変更。並列ビルド時のディスク枯渇を解消。
v3.4.5 - YouTube配信エンコーダ3段階フォールバック・Dockerfile修正
変更点:
- YouTube 配信エンコーダを QSV → VAAPI → libx264 の3段階フォールバックに拡張
- Intel QSV 利用可能時: h264_qsv 720p 2000kbps（N100 等最新 Intel）
- QSV 不可・VAAPI 利用可能時: h264_vaapi 720p 2000kbps（旧世代 Intel / AMD GPU）
- どちらも不可: libx264 ultrafast 720p 2000kbps（CPU エンコード）
- Dockerfile.dashboard を python:3.11-slim-bookworm (Debian 12) ベースに変更
- Docker Desktop for Mac の時刻ずれによる GPG 署名エラーを解消
- Ubuntu 専用の libmfx-gen1.2 パッケージを削除
v3.4.4 - YouTube配信のマルチプラットフォーム対応
新機能・変更点:
- Intel QSV ハードウェアエンコードを自動検出し利用可能な場合は h264_qsv でエンコード
- QSV 非対応環境（Apple Silicon 等）は libx264 ultrafast に自動フォールバック
- YouTube 配信に自動再接続ループを追加（切断後 15 秒待機して再接続）
- 映像解像度を 1280×720 に統一（CPU/GPU 負荷軽減）
- Dockerfile.dashboard を Ubuntu 24.04 ベースに変更し Intel QSV パッケージを整備
v3.3.0 - YouTube Live配信
新機能:
- ダッシュボードからカメラ単位でYouTube Liveへの配信開始/停止が可能
- streamers ファイルの4番目のフィールドに youtube:STREAM_KEY を指定
- ダッシュボードコンテナ内の ffmpeg サブプロセスが go2rtc の RTSP リレー経由で映像を取得し、YouTube に直接 RTMP 送信
- 配信中は「配信中 LIVE」ボタンがパルスアニメーションで表示
- 10秒間隔でプロセス状態を確認して配信状態を自動ポーリング
設定例:
# streamers ファイル
rtsp://user:pass@192.0.2.11/live || 南カメラ | youtube:xxxx-xxxx-xxxx-xxxx
新規環境変数:
- CAMERA{i}_YOUTUBE_KEY — YouTubeストリームキー
- CAMERA{i}_RTSP_URL — RTSP URL（ffmpeg AAC変換用）
- GO2RTC_API_URL — go2rtc APIのURL（通常は自動設定）
注意事項:
- YouTube は H.264 映像 + AAC 音声が必須。dashboard コンテナ内の ffmpeg が自動的に変換する
- ffmpeg は -re フラグでリアルタイム読み込みを強制し、バースト送信を防止
v3.2.1 - 手動録画一覧表示改善
手動録画の一覧表示を改善。manual_recordings/<camera>/ 配下の録画ファイルが正しくリストアップされるよう修正。
v3.2.0 - 手動録画機能
新機能:
- ダッシュボードから任意タイミングで録画予約が可能（録画予約 UI）
- 手動録画の保存先: manual_recordings/<camera>/
v3.1.0 - WebRTC/go2rtc サポート
新機能:
- generate_compose.py に --streaming-mode webrtc オプションを追加
- --go2rtc-candidate-host <IP> でWebRTC candidateホストを上書き指定可能（未指定時は自動検出）
- go2rtc.yaml の自動生成（--go2rtc-config で出力先変更可）
- ダッシュボード環境変数 CAMERA1_STREAM_KIND=webrtc / CAMERA1_STREAM_URL によるWebRTC埋め込み表示
使用例:
python generate_compose.py \
--streamers streamers \
--streaming-mode webrtc \
--go2rtc-candidate-host 192.0.2.10
v1.16.0 - 画面端ノイズ除外
新規パラメータ:
- EXCLUDE_EDGE_RATIO（環境変数、デフォルト: 0.0、範囲: 0.0-0.2）
- --exclude-edge-ratio（コマンドライン引数）
機能: 画面四辺（上下左右）から指定割合を除外し、端部のノイズや歪みによる誤検出を防止
使用例:
python generate_compose.py --exclude-edge-ratio 0.05
ダッシュボードから即時反映可能（再起動不要）
v1.14.0 - 録画マージン設定
新規パラメータ:
- clip_margin_before: 検出前の追加録画時間（秒）
- clip_margin_after: 検出後の追加録画時間（秒）
機能: 流星検出イベントの前後に余裕を持たせて録画
デフォルト値: 0.0秒（両方）
推奨値: 0.5秒（両方）
使用例:
environment:
- CLIP_MARGIN_BEFORE=0.5
- CLIP_MARGIN_AFTER=0.5
ダッシュボードから即時反映可能（再起動不要）
v1.13.0 - 全カメラ設定UI
新機能:
- /settings ページによる全カメラへの一括設定
- 設定差分のハイライト表示
- output/runtime_settings/<camera>.json への永続化
即時反映項目（再起動不要）: - 検出パラメータ（diff_threshold, min_brightness, min_linearity等） - ノイズ除外パラメータ - マスク設定 - 録画マージン設定（v1.14.0+） - 画面端除外設定（v1.16.0+）
自動再起動項目（再ビルド不要）: - sensitivity, scale, buffer, extract_clips
メリット: - Docker再ビルド不要で設定変更可能 - 設定が永続化され、再起動後も維持 - 複数カメラへの設定を一括適用
v1.12.0 - ノイズ帯マスク
新規パラメータ:
- nuisance_mask_image: 事前生成済みノイズ帯マスク画像
- nuisance_from_night: 夜間画像からマスク自動生成
- nuisance_dilate: マスク拡張ピクセル数（デフォルト: 3）
- nuisance_overlap_threshold: 重複率閾値（デフォルト: 0.3）
機能: 電線、部分照明など固定された線状ノイズを除外
通常マスクとの違い: - 通常マスク: 領域内の検出を完全に無効化 - ノイズ帯マスク: 軌跡がノイズ帯と一定以上重複した場合のみ除外
使用例:
environment:
- NUISANCE_FROM_NIGHT=/app/night_with_wires.jpg
- NUISANCE_DILATE=5
- NUISANCE_OVERLAP_THRESHOLD=0.25
ダッシュボードから閾値を即時調整可能
関連ドキュメント
- OPERATIONS_GUIDE.md - 運用ガイド
- DETECTOR_COMPONENTS.md - 検出アルゴリズム詳細
- DOCKER_ARCHITECTURE.md - Docker構成
- SECURITY.md - セキュリティガイド