# NavSea Codex Task
# Karatsu AOI Vector Tile Build
Architecture: NavSea V11 / Codex6
Scope: Server Side Tile Build

---

# Task Name

NavSea_Karatsu_AOI_PBF_Builder

---

# Task Goal

Generate a NavSea Vector Tile dataset for the area surrounding **Karatsu City (唐津市)**.

The tile build must cover approximately:

```
10 nautical mile radius
centered on Karatsu city
```

The tiles must be generated for **all zoom levels supported by NavSea**.

The generated tiles will be used to validate:

- semantic overlay
- render compatibility
- navigation object detection
- tile density behavior
- style compatibility

---

# Output Location

Tiles must be written to:

```
/home/wwwroot/pbf
```

Directory structure must follow standard vector tile layout:

```
/home/wwwroot/pbf/{z}/{x}/{y}.pbf
```

Example:

```
/home/wwwroot/pbf/10/864/440.pbf
```

Existing files in the directory may be overwritten.

---

# AOI Definition

Center location:

```
Karatsu City
Japan
```

Recommended reference coordinate:

```
Lat: 33.4425
Lon: 129.9697
```

Coverage radius:

```
10 nautical miles
≈ 18.52 km
```

Codex may implement this AOI using one of the following:

```
1 center point + radius
2 bounding box derived from radius
3 tile range approximation
```

The resulting tiles must fully cover the requested radius.

---

# Zoom Levels

Tiles must be generated for:

```
z = 0 → 14
```

(Or the maximum zoom available in the dataset.)

---

# Data Sources

Tile features must be built from the validated NavSea semantic dataset.

Primary semantic source:

```
pbf_relayer_candidates
```

Additional required tables:

```
features
properties
at_attributes
feature_semantic
```

These tables must be joined to reconstruct the full feature.

---

# Feature Reconstruction Rules

Each output tile feature must include:

## Geometry

From:

```
features
```

Fields:

```
z
x
y
geom_type
```

The geometry encoding must match the original vector tile geometry.

---

## Original Attributes

All original attributes from:

```
properties
```

must be preserved.

Examples include:

```
class
shape
name
symbol
depth
category
```

These attributes must **not be removed or renamed**.

---

## Semantic Attributes

Additional semantic fields must be included from:

```
pbf_relayer_candidates
```

Including:

```
canonical_object_type
canonical_family
semantic_key
detection_key
render_layer
```

These fields must be **added**, not replacing original fields.

---

# Feature Selection

Features must be selected based on tile coordinates intersecting the AOI.

Selection process:

```
1 determine tile range covering AOI
2 select features matching tile coordinates
3 group features by tile
4 encode each tile
```

---

# Tile Encoding

Each tile must be encoded as a **Mapbox Vector Tile (MVT)**.

Encoding rules:

```
Layer name = render_layer
```

If `render_layer` is null, fallback to:

```
source_layer
```

Geometry must be encoded according to:

```
geom_type
```

---

# Performance Requirements

The tile builder must:

```
avoid full-table scans where possible
use tile coordinate filtering
process tiles incrementally
```

The builder must not attempt to load the entire dataset into memory.

---

# Build Script

Codex must implement a script:

```
navsea_tile_builder.py
```

Capabilities required:

```
AOI tile calculation
database feature extraction
tile grouping
vector tile encoding
parallel tile generation
filesystem output
```

---

# Suggested Execution

The build script should be executable as:

```bash
python navsea_tile_builder.py \
--center-lat 33.4425 \
--center-lon 129.9697 \
--radius-nm 10 \
--zmin 0 \
--zmax 14 \
--output /home/wwwroot/pbf
```

---

# Expected Result

After the build completes, the directory should contain:

```
/home/wwwroot/pbf/
 ├─ 0/
 ├─ 1/
 ├─ 2/
 ├─ ...
 └─ 14/
```

Each containing:

```
{x}/{y}.pbf
```

The tiles must render correctly in MapLibre / OpenCPN / tile viewers.

---

# Verification

After build, the following checks should pass:

```
tiles exist for requested AOI
tile hierarchy is correct
vector tiles decode successfully
original attributes preserved
semantic fields present
```

Example feature should resemble:

```json
{
  "class": "灯",
  "shape": "灯標",
  "name": "唐津灯台",

  "canonical_object_type": "navigation_light",
  "canonical_family": "navigation_aid",
  "detection_key": "nav_light"
}
```

---

# End Task