# Forestry Operations Lite — Help

# Forestry Operations Lite — ヘルプ

EN/JP

## Data Setup Hints

### About scipy (required for Flow Buffer / DEM resampling / SHC computation)

Without scipy, Flow Buffer display, fine-resolution DEM resampling, and SHC computation do not work (other features are unaffected).

Windows (standard installer): scipy is normally already included. If it's genuinely missing, close QGIS and run in Command Prompt from your QGIS install's `bin` folder (e.g. `C:\Program Files\QGIS 4.x\bin\`):
`python-qgis-ltr.bat -m pip install --user scipy`
(The filename may be `python-qgis.bat` depending on your install; adjust the path to match your QGIS version.)

Linux: close QGIS and run in a terminal:
`sudo apt install python3-scipy`

To check what's actually loaded after installing, run the following in QGIS's Python Console:
`import numpy, scipy`
`print(numpy.__file__, numpy.__version__)`
`print(scipy.__file__, scipy.__version__)`

### DEM / DSM/DTM Data

- Select a general-purpose DEM, or one covering the area where you'll run the terrain analysis.
- Select a DSM covering the same extent as the DEM data.
- Selecting DSM data lets the runoff and velocity coefficients for flow estimation be calculated automatically from the DSM.

### TIF / ZIP Layout

Pattern | Action
--- | ---
Single TIF | Select the file directly
Single ZIP (containing a TIF) | Select the ZIP directly
Merge multiple ZIPs | Place all ZIPs for the same region in one folder and select that folder. A `merged_<folder name>.tif` is auto-generated in the parent folder.
Reuse a merged TIF | Select the generated `merged_*.tif` directly to skip re-merging.

## Parameter Setting Hints

### Slope Stability (Infinite Slope Model)

Computes the slope stability factor of safety (FS) using the infinite slope model.
FS is calculated from slope angle, internal friction angle, cohesion, soil depth, and saturation ratio.
FS < 1.0: collapse risk　/ FS < FS threshold: caution
All parameters describe the properties of the "topsoil down to the hard layer".

Parameter | Guideline / how to check on-site
--- | ---
Internal friction angle φ' Interlock of topsoil particles | Check by picking up and squeezing soil in your hand on site. ・Holds shape when squeezed but crumbles when wet → φ 20–28° (fine sand/clay, slopes with surface wash marks after rain) ・Forms a clump when squeezed but breaks apart → φ 30–35° (typical mountain soil/loam in cedar/cypress plantations) ・Doesn't hold shape, feels gritty → φ 38°+ (gravel/rock debris, ridgelines, near-bedrock layers)
Cohesion c' Stickiness/bonding of topsoil | ・Sandy soil, young stand with shallow roots → 0 kPa ・Gravelly loam, mid-age stand → 5 kPa ・Organic clay soil → 10–20 kPa
Soil depth z Thickness of topsoil | Dig or probe with a backhoe or steel rod to the boundary where the layer changes (color/hardness/grain size). The hard layer is a candidate slip surface.
Saturation ratio m | ・0.5 = half-saturated (normal conditions) ・0.9 = after heavy rain
FS threshold | Try different thresholds (e.g. 1.5 for danger, 2.5 for caution) to see how the distribution changes. Prefer on-site test values if available.

### Valley Terrain (TWI)

TWI (Topographic Wetness Index) = ln(A / tan(β)) identifies wet zones.
Higher values indicate valleys/lowlands where water tends to accumulate.

Parameter | Concept
--- | ---
TWI threshold | Filters areas below the set value as dry terrain. Setting 8.0 extracts mainly valley areas prone to wetness. Raising the value increases areas classified as dry, missing more wet terrain.
Minimum catchment area | Lower bound for excluding small flow paths. Smaller values detect finer valley terrain.

### Flow Direction Method (Valley/TWI only)

Choose from 3 methods for how water is routed when computing TWI and valley zones. This choice affects Valley Terrain (TWI) only — flow estimation always uses D8.
It's a trade-off between "how sharp the valley lines are" and "how accurate the wetness distribution is".

D8 (Single Steepest) | D∞ (Tarboton) | MFD (Multiple Flow Direction)
--- | --- | ---
Routes water to a single cell. Produces a sharp, single-line valley, but vertical striping artifacts appear on the TWI surface. | Splits flow between 2 adjacent cells. No striping, and the valley line is reasonably preserved — an intermediate approach. | Distributes flow across all downslope directions. Smoothest wetness distribution. Valleys follow the bottom of the terrain but are thick and diffuse.
Use for: identifying dangerous channels where water concentrates (collapse-prone channels, channels to avoid when routing roads). | Use for: when you want a surface that keeps the line while avoiding striping. | Use for: representing valley terrain accurately as a surface (wetness/hazard surface).

Reference values (same sample DEM as above, 2m, matched valley area — analysis area: 72 ha)

Method | Approx. TWI threshold | Extracted valley area | Share (of 72 ha)
--- | --- | --- | ---
D8 | approx. 5.2 | 2.01 ha | 2.8%
D∞ | approx. 5.4 | 2.21 ha | 3.1%
MFD | approx. 5.9 | 2.87 ha | 4.0%

How to read this: A method with a small share and thin lines (D8) points to "dangerous channels." A method with a large share and thick areas (MFD) represents "the valley terrain itself" as a surface.

Because the catchment scale differs by method, the TWI threshold needed to match the same valley area shifts between methods. When switching methods, re-adjust the TWI threshold above (e.g., 5.2 for D8 → around 5.9 for MFD).

The three images above are illustrative renderings showing the behavioral differences between methods, not plugin output. They were rendered from a sample DEM (2m resampled) solely to illustrate the differences. Actual output (`twi.tif`, `valley_zones.gpkg`) is generated by running the analysis.

### Flow Estimation (Modified Rational Method with Time of Concentration)

Estimates flow using the modified rational method plus time-of-concentration (Tc) routing.
`Q = (1/360) × C × i × A_eff　　A_eff = A × min(1, T/Tc)`
Catchments where duration T is shorter than Tc have suppressed flow.

Parameter | Concept
--- | ---
i_peak (peak rainfall intensity) | 50 mm/h assumes "a heavy storm of 50mm in 1 hour"
Runoff coefficient C | 0.8 means about 80% of rainfall is calculated as surface runoff
Total precipitation | 100 mm is a case totaling 100mm from start to end of rainfall
Duration T | 6 h computes average/total flow assuming 6 hours of continuous rain
Velocity coefficient | Guideline: forest 0.3 / grassland 0.6 / paved surface 1.5 m/s. When DSM/DTM is set, the runoff and velocity coefficients are auto-calculated from canopy height.

## Output Files

File name | Contents
--- | ---
`twi.tif` | Drainage / seepage / mud risk (Topographic Wetness Index)
`stability_fs.tif` | Slope stability (FS raster)
`integrated_risk_index.tif` | Integrated risk index (0–6)
`integrated_high_risk.gpkg` | High-priority area polygons
`valley_zones.gpkg` | Valley shape / catchment terrain vector
`flow_peak.tif` | Peak flow Qp [m³/s]
`flow_mean.tif` | Mean flow Qm [m³/s]
`flow_vtotal.tif` | Total flow volume V [m³]

## Feature Descriptions

### Slope Stability

Computes the stability factor FS using the infinite slope model. FS < 1.0 indicates collapse risk, FS < 1.5 indicates a caution zone. Calculated from soil parameters (φ, c, γ), terrain slope, and soil depth.

### Valley Terrain

Vector data extracted from the DEM, showing catchment terrain and valley lines. Used to check for interference with the drainage network when planning road/skid-trail networks.

### Wetness Terrain

Topographic Wetness Index (TWI) raster. Higher values indicate greater water accumulation, poor drainage, weak ground, and higher mud risk.

### Flow Estimation

Estimates per-cell peak and mean flow plus total flow volume using the modified rational method (Q = CiA/360). When DSM is set, the runoff coefficient varies per location based on canopy height.

### Integrated Risk

An additive risk index (0–6) combining FS, TWI, and peak flow. Extracts areas where multiple hazard factors overlap as "high-priority" polygons.

Forestry Operations Lite | Developed by Avid Tree Work

## データ設定ヒント

### scipy について（Flow Buffer / DEM リサンプル / SHC 計算に必須）

scipy が無い場合、Flow Buffer 表示・高解像度 DEM のリサンプル・SHC 計算が動作しません（他の機能には影響しません）。

Windows（標準インストーラー）：通常はscipyが最初から入っています。本当に無い場合は、QGISを閉じてから、QGISインストール先の`bin`フォルダ（例：`C:\Program Files\QGIS 4.x\bin\`）でコマンドプロンプトを開き、以下を実行してください：
`python-qgis-ltr.bat -m pip install --user scipy`
（ファイル名は環境によって`python-qgis.bat`の場合もあります。パスはお使いのQGISバージョンに合わせてください。）

Linux：QGISを閉じてから、ターミナルで以下を実行してください：
`sudo apt install python3-scipy`

インストール後、実際に読み込まれているものを確認するには、QGISのPythonコンソールで以下を実行してください：
`import numpy, scipy`
`print(numpy.__file__, numpy.__version__)`
`print(scipy.__file__, scipy.__version__)`

### DEM / DSM/DTM データ

- DEM は汎用データか、地形解析を行う箇所のデータを選択してください。
- DSM データは、地表データの DEM データ設定と範囲を同じくするデータを選んでください。
- DSM データを選択することで流量推測における流出係数・流速係数がDSMを基に自動計算されます。

### TIF / ZIP の配置

パターン | 操作
--- | ---
単体 TIF | そのままファイルを選択
ZIP 1 枚（TIF 入り） | ZIP を直接選択
複数 ZIP 結合 | 同一地域の複数 ZIP を 1 つのフォルダに配置し、そのフォルダを選択。 親フォルダに `merged_<フォルダ名>.tif` が自動生成されます。
結合済み TIF の再利用 | 生成された `merged_*.tif` を直接選択することで再結合を省けます。

## パラメータ設定ヒント

### 斜面安定（無限斜面モデル）

無限斜面モデルで斜面安定指数（FS）を算出します。
FS は傾斜角・内部摩擦角・粘着力・土壌深度・飽和率から計算されます。
FS < 1.0：崩壊危険　/ FS < FS閾値：要注意
いずれのパラメータも「硬い層までの表土」の性質を入力します。

パラメータ | 目安・現場での確認方法
--- | ---
内部摩擦角 φ' 表土粒子の噛み合わせ | 現場で土を手に取り握って確認。 ・握ると形が残るが水を含むとドロッと崩れる → φ 20〜28° （細かい砂・粘土質・雨後に表面が流れた跡のある斜面） ・握ると固まるが砕ける → φ 30〜35° （一般的な杉・檜植林地の山土・壌土） ・握っても形にならずざらざらする → φ 38°〜 （礫・岩屑混じり・尾根筋・岩盤に近い層）
粘着力 c' 表土の粘り・団結力 | ・砂質で根系の浅い若齢林 → 0 kPa ・礫混じり壌土・中齢林 → 5 kPa ・有機質を含む粘性土 → 10〜20 kPa
土壌深度 z 表土の厚さ | バックホウや鉄芯で掘削・刺込み、層の変わり目（色・硬さ・粒径が変わる箇所）まで計測。 硬い層が滑り面の候補となります。
飽和率 m | ・0.5 = 半分濡れた状態（平常時） ・0.9 = 大雨後の状態
FS 閾値 | 1.5 以下を危険、2.5 以下を要注意など、基準を変えて分布の変化を確認。 現場試験値がある場合はそちらを優先してください。

### 沢地形（TWI）

TWI（地形湿潤指数）= ln(A / tan(β)) で湿潤帯を識別します。
値が大きいほど水が集まりやすい谷・低地を示します。

パラメータ | 考え方
--- | ---
TWI 閾値 | 設定値以下を乾燥地形としてフィルタリング。 8.0 にすると湿りやすい谷部を中心に抽出。値を上げると乾燥地とみなす箇所が増え、 湿潤地が拾えなくなります。
最小集水面積 | 小さい水みちを除外する下限サイズ。小さい値ほど細かい沢地形も検出されます。

### 流向方式（Valley/TWI 専用）

TWI と沢ゾーンを計算するときの水の流し方を3方式から選べます。 この選択は沢地形（TWI）のみに効き、流量推測は常に D8 です。
「沢の線のくっきりさ」と「湿り分布の正確さ」のトレードオフになります。

D8（単一最急） | D∞（Tarboton） | MFD（多方向）
--- | --- | ---
水を1マスにだけ流す。沢が細い1本線でくっきり出るが、TWI面に縦縞のアーティファクトが出る。 | 隣接2マスに分けて流す。縞が出ず沢の線もそこそこ残る中間型。 | 下り方向すべてに分配。最もなめらかな湿り分布。沢は谷底に沿うが太く曖昧。
用途：水が集まる危険筋の特定（崩れやすい筋・道で避ける筋）。 | 用途：線も残しつつ縞のない面が欲しいとき。 | 用途：沢地形を面として正確に（湿り・災害リスク面）。

数値の目安（上図と同じサンプルDEM・2m・沢の量を揃えた場合：解析対象 72 ha）

方式 | TWI 閾値の目安 | 抽出された沢面積 | 占有率（対 72 ha）
--- | --- | --- | ---
D8 | 約 5.2 | 2.01 ha | 2.8%
D∞ | 約 5.4 | 2.21 ha | 3.1%
MFD | 約 5.9 | 2.87 ha | 4.0%

読み方：占有率が小さく線が細い方式（D8）＝「危険な筋」を指し示す。 占有率が大きく面が太い方式（MFD）＝「沢地形そのもの」を面で表す。

集水のスケールが方式で変わるため、同じ沢の量にするのに必要な TWI 閾値が方式ごとにズレます。 方式を切り替えたら上の TWI 閾値 を再調整してください（例：D8 で 5.2 → MFD なら 5.9 前後）。

上の3枚は各方式の挙動の違いを示す説明用の描画例であり、プラグインの成果物ではありません。 違いを示すためだけにサンプルDEM（2mリサンプル）で描画したものです。 実際の出力（`twi.tif`・`valley_zones.gpkg`）は解析を実行して生成されます。

### 流量推測（修正合理式・到達時間考慮）

修正合理式＋到達時間（Tc）ルーティングで流量を推定します。
`Q = (1/360) × C × i × A_eff　　A_eff = A × min(1, T/Tc)`
継続時間 T が Tc より短い集水域は流量が抑制されます。

パラメータ | 考え方
--- | ---
i_peak（最大降雨強度） | 50 mm/h で「1時間 50mm の豪雨」を想定
流出係数 C | 0.8 なら雨の約 8 割が地表流として計算されます
総降水量 | 100 mm で降り始めから終わりまで合計 100 mm のケース
継続時間 T | 6 h で 6 時間続く降雨として平均流量・総流量を計算
流速係数 | 林地 0.3 / 草地 0.6 / 舗装面 1.5 m/s が目安。 DSM/DTM を設定した場合、流出係数・流速係数は樹冠高さから自動計算。

## 出力ファイル一覧

ファイル名 | 内容
--- | ---
`twi.tif` | 排水・湧水・ぬかるみ（地形湿潤指数）
`stability_fs.tif` | 斜面安定性（FS ラスタ）
`integrated_risk_index.tif` | 総合リスク指標（0〜6）
`integrated_high_risk.gpkg` | 重点箇所ポリゴン
`valley_zones.gpkg` | 沢形状・集水地形ベクター
`flow_peak.tif` | ピーク流量 Qp [m³/s]
`flow_mean.tif` | 平均流量 Qm [m³/s]
`flow_vtotal.tif` | 総流量体積 V [m³]

## 機能説明

### 斜面安定

無限斜面モデルによる安定性係数 FS を算出。FS < 1.0 で崩壊リスク、FS < 1.5 で注意域。 土質パラメータ（φ・c・γ）と地形勾配・土層深から計算。

### 沢地形

DEM から集水地形・沢筋を抽出したベクターデータ。 路網や作業道計画での水系との干渉確認に使用。

### 湿潤地形

地形湿潤指数（TWI）ラスタ。値が高いほど水が集まりやすく排水不良・ 地盤軟弱・ぬかるみリスクが高い。

### 流量推測

修正合理式（Q = CiA/360）による各セルのピーク・平均流量と総流量体積を推計。 DSM 設定時は樹冠高から流出係数を地点ごとに可変。

### 総合リスク

FS・TWI・流量ピークを統合した加算型リスク指標（0〜6）。 複数の危険因子が重なる箇所を「重点箇所」ポリゴンで抽出。

Forestry Operations Lite | Developed by Avid Tree Work