English

# PhotoView360

A QGIS plugin that instantly opens a 360-degree panoramic image in your browser by clicking a feature in a vector layer.
The viewer is powered by A-Frame and requires no additional installation.

## Requirements

Item | Requirement
--- | ---
QGIS | 3.0 or later
Python | 3.x (bundled with QGIS)
Browser | Chrome / Edge / Firefox (A-Frame compatible)
Image format | JPEG / PNG (equirectangular 360° images recommended)

## Installation

1. Copy the `photoview360` directory to your QGIS plugin folder:
   `C:\Users\<username>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\`
2. Open QGIS and go to Plugins → Manage and Install Plugins
3. Enable PhotoView360

## Usage

### 1. Open the dialog

Click the PhotoView360 icon in the toolbar, or go to Plugins → PhotoView360 → PhotoView360.

### 2. Configure the layer and path

Select a vector layer containing photo locations in Photo Layer.
Then choose how to specify the image path:

Mode | Description
--- | ---
① Full path via attribute field | Select a field that stores the absolute path to the image (e.g. `C:\photos\IMG_001.jpg`).
② Filename via attribute field | Select a field that stores the filename (e.g. `IMG_001.jpg`) and specify the image folder separately. Check Include subfolders to search recursively.

### 3. Select a location and open the viewer

1. Click Select photo location to activate the tool (the button will appear pressed)
2. Click a feature on the map — the browser opens automatically with the 360° viewer
3. The selected feature is highlighted in red on the map

### Viewer controls

Action | Result
--- | ---
Drag | Rotate view
Mouse wheel | Zoom in / out (follows cursor direction)

### Language toggle

Click the English / 日本語 button at the top-right of the dialog to switch the UI language instantly.

## How it works

- Feature clicks are detected via `QgsMapToolIdentify`
- A local HTTP server (Python standard library) is started for the image folder and serves images via `localhost`
- The image is rendered as a sphere using A-Frame's `<a-sky>` component
- The server is reused as long as the folder remains the same; the port is assigned automatically by the OS

## Author & License

Author: Rei Ito <katzchen.th@gmail.com>
License: GNU GPL v2 or later

日本語

# PhotoView360

QGIS ベクターレイヤーのフィーチャをクリックするだけで、 関連付けられた 360度パノラマ画像をブラウザで即時表示 する QGIS プラグインです。
ビューアーは A-Frame を使用しており、追加インストール不要で動作します。

## 動作環境

項目 | 要件
--- | ---
QGIS | 3.0 以上
Python | 3.x（QGIS 同梱）
ブラウザ | Chrome / Edge / Firefox（A-Frame 対応）
画像形式 | JPEG / PNG（等長方形射影の 360 度画像を推奨）

## インストール

1. プラグインフォルダに `photoview360` ディレクトリをコピー
   `C:\Users\<ユーザー名>\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\`
2. QGIS を起動し、メニュー プラグイン → プラグインの管理とインストール を開く
3. PhotoView360 を有効化する

## 使い方

### 1. ダイアログを開く

ツールバーの PhotoView360 アイコン、またはメニュー プラグイン → PhotoView360 → PhotoView360 をクリックします。

### 2. レイヤーとパスの設定

フォトレイヤー で360度写真の位置情報を持つベクターレイヤーを選択します。
次に、画像パスの指定方法を選んでください：

モード | 説明
--- | ---
① フルパスを属性フィールドで指定 | 画像の絶対パス（例：`C:\photos\IMG_001.jpg`）が格納されているフィールドを選択します。
② ファイル名を属性フィールドで指定 | ファイル名（例：`IMG_001.jpg`）が格納されているフィールドを選択し、画像の保存フォルダを別途指定します。「サブフォルダを含む」にチェックを入れると、サブフォルダ内も再帰検索します。

### 3. 撮影地点を選択してビューアーを開く

1. 撮影地点を選択 ボタンをクリックしてアクティブにします（ボタンが押し込み状態になります）
2. 地図上のフィーチャをクリックすると、ブラウザが自動的に開き 360 度ビューアーが表示されます
3. 選択したフィーチャは地図上で赤くハイライト表示されます

### ビューアーの操作

操作 | 動作
--- | ---
ドラッグ | 視点を回転
マウスホイール | ズームイン / ズームアウト（マウスカーソル方向に追従）

### 言語切替

ダイアログ右上の English / 日本語 ボタンで UI 言語を即座に切り替えられます。

## 仕組み

- フィーチャのクリックを `QgsMapToolIdentify` で検出
- 画像フォルダに対して ローカル HTTP サーバー（Python 標準ライブラリ）を立ち上げ、`localhost` 経由で画像を配信
- A-Frame の `<a-sky>` コンポーネントで等長方形射影画像を球面マッピング
- サーバーはフォルダが変わるまで再利用（ポートは OS が自動割り当て）

## 作者・ライセンス

Author: Rei Ito <katzchen.th@gmail.com>
License: GNU GPL v2 or later