Merge feat/canonical-vertices-orientation: canonical rectangle vertices + orientation vocabulary

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kunifujiwara

HISTORY.rst

@@ -2,6 +2,22 @@
 History
 =======
 
+1.4.0 (2026-07-05)
+------------------
+
+* ``rectangle_vertices`` are now validated and canonicalized to
+  ``[SW, NW, NE, SE]`` order at all public entry points (``get_voxcity``,
+  ``get_voxcity_CityGML`` and the four grid functions). Non-canonical
+  input is reordered with a warning; closed 5-point rings are accepted;
+  out-of-range lon/lat raises ``ValueError`` with a (lat, lon) hint.
+* Grid orientation conversions (GeoTIFF, MagicaVoxel, OBJ, rasterio
+  interop, coastline masks) now go through named helpers in
+  ``voxcity.utils.orientation``. No behavior change. The ENVI-met exporter
+  intentionally remains an exception: it keeps SOUTH_UP internally and
+  writes north-first rows only at the file-format boundary.
+* Fixed contradictory 3D orientation statements in the documented grid
+  contract.
+
 0.1.0 (2024-08-01)
 ------------------
 

docs/coordinate_systems_ja.md

@@ -83,9 +83,14 @@ GeoTIFF を読むときはファイル自身の CRS を尊重し、必要時の
 
 座標系とは別に格子の行方向の規約がある（[utils/orientation.py](../src/voxcity/utils/orientation.py)）：
 
-- 内部処理は **south_up**（行0＝南＝原点辺、行increase で北へ／列increase で東へ）
-- 可視化時のみ `np.flipud` で north_up に反転
-- 変換は `ensure_orientation()` のみで行う（境界での正規化用）
+- 内部処理は **south_up**（行0＝南＝原点辺、行increase で北へ／列increase で東へ）。3D ボクセル配列も水平方向は同じ向き（フリップなし）
+- 境界（I/O）での向き変換はすべて `utils/orientation.py` の名前付きヘルパーに集約：
+  - `ensure_orientation()` — south_up ⇔ north_up の縦フリップ（GeoTIFF・海岸線マスク・可視化など）
+  - `to_rasterio_layout()` / `from_rasterio_layout()` — uv 格子 ⇔ rasterio の (ny, nx) レイアウト（純粋な転置）
+  - `grid_to_rotated_raster()` — 回転 AOI 用 GeoTIFF のレガシーレイアウト
+  - `voxels_to_magicavoxel_axes()` / `voxels_to_kji()` — 3D ボクセルのフォーマット別軸順
+- **例外**：ENVI-met エクスポータは内部を south_up のまま保持し、行を北先頭で書き出す整形をファイル形式境界で行う（`arr[::-1]`）。これは意図的な設計で、`ensure_orientation()` は呼ばない（`tests/test_exporter_envimet.py` の `TestEnvimetSouthUpProcessing` がこれを保証）
+- `rectangle_vertices` は公開 API 入口で `normalize_rectangle_vertices()` により正準順 [SW, NW, NE, SE] に正規化される（非正準順は警告付きで並べ替え）
 
 ---
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "voxcity"
-version = "1.3.9"
+version = "1.4.0"
 description = "voxcity is an easy and one-stop tool to output 3d city models for microclimate simulation by integrating multiple geospatial open-data"
 readme = "README.md"
 license = "MIT"

src/voxcity/downloader/ocean.py

@@ -21,6 +21,12 @@
 import requests
 import numpy as np
 
+from ..utils.orientation import (
+    ensure_orientation,
+    ORIENTATION_NORTH_UP,
+    ORIENTATION_SOUTH_UP,
+)
+
 # Cache directory for ocean detection results (optional)
 CACHE_DIR = Path(tempfile.gettempdir()) / "voxcity_ocean_cache"
 
@@ -603,7 +609,7 @@ def apply_ocean_mask_to_grid(
         rectangle_vertices,
         grid.shape
     )
-    land_mask = np.flipud(land_mask)
+    land_mask = ensure_orientation(land_mask, ORIENTATION_NORTH_UP, ORIENTATION_SOUTH_UP)
 
     # Apply ocean class to cells that are:
     # 1. Not land (ocean according to OSM land polygons)

src/voxcity/exporter/geotiff.py

@@ -12,6 +12,7 @@
 from affine import Affine
 
 from ..geoprocessor.raster.core import compute_grid_geometry, compute_cell_center_coords
+from ..utils.orientation import grid_to_rotated_raster
 
 __all__ = [
     "export_grid_geotiff",
@@ -105,7 +106,7 @@ def _north_up_affine_and_array(grid, rectangle_vertices, meshsize):
         dx * u_vec[0], -dy * v_vec[0], float(nw[0]),
         dx * u_vec[1], -dy * v_vec[1], float(nw[1]),
     )
-    array = np.ascontiguousarray(np.flipud(grid.T))
+    array = grid_to_rotated_raster(grid)
     return array, transform
 
 

src/voxcity/exporter/magicavoxel.py

@@ -25,6 +25,7 @@
 import os
 from ..visualizer import get_voxel_color_map
 from ..utils.logging import get_logger
+from ..utils.orientation import voxels_to_magicavoxel_axes
 
 _logger = get_logger(__name__)
 
@@ -212,11 +213,7 @@ def numpy_to_vox(array, color_map, output_file):
     value_mapping = create_mapping(color_map)
     value_mapping[0] = 0  # Ensure 0 maps to 0 (void)
 
-    # VoxCity arrays use (north, east, height). pyvox expects dense arrays as
-    # (y, z, x), and pyvox flips dense z internally when writing MagicaVoxel
-    # voxels. Pre-flip height so MagicaVoxel receives z=height.
-    array_flipped = np.flip(array, axis=2)
-    array_transposed = np.transpose(array_flipped, (0, 2, 1))  # (north, height, east)
+    array_transposed = voxels_to_magicavoxel_axes(array)  # (north, height, east)
     mapped_array = np.vectorize(value_mapping.get)(array_transposed, 0)
 
     # Create and save vox file

src/voxcity/exporter/obj.py

@@ -46,6 +46,7 @@
 from ..visualizer import get_voxel_color_map
 from ..errors import ConfigurationError
 from ..utils.logging import get_logger
+from ..utils.orientation import voxels_to_kji
 
 _logger = get_logger(__name__)
 
@@ -387,7 +388,7 @@ def export_obj(array, output_dir, file_name, voxel_size=None, voxel_color_map=No
     # scene-space vertices: X = v/east (axis 1 of original), Y = u/north (axis 0),
     # Z = height (axis 2). Consistent with the Phase 3 uv-domain contract in
     # src/voxcity/simulator/common/coordinates.py.
-    array = array.transpose(2, 0, 1)  # (nk=height, ni=north/u, nj=east/v)
+    array = voxels_to_kji(array)  # (nk=height, ni=north/u, nj=east/v)
     size_x, size_y, size_z = array.shape  # size_x=height, size_y=north, size_z=east
 
     # Initialize data structures

src/voxcity/generator/__init__.py

@@ -5,7 +5,8 @@
 
 Orientation contract:
 - All 2D grids use uv_m/SOUTH_UP orientation (axis 0 = u/north, row 0 = southern origin edge; axis 1 = v/east).
-- 3D indexing follows (row, col, z) = (north→south, west→east, ground→up).
+- 3D voxel arrays index (i, j, k) with the same horizontal orientation as the
+  2D grids (row 0 = southern origin edge, i increases northward) and k = ground→up.
 """
 
 from .api import get_voxcity, get_voxcity_CityGML, auto_select_data_sources

src/voxcity/generator/api.py

@@ -26,6 +26,7 @@
 )
 from ..utils.lc import get_land_cover_classes
 from ..geoprocessor.io import get_gdf_from_gpkg
+from ..geoprocessor.utils import normalize_rectangle_vertices
 from ..visualizer.grids import visualize_numerical_grid
 from ..utils.logging import get_logger
 
@@ -466,7 +467,9 @@ def get_voxcity(rectangle_vertices, meshsize, building_source=None, land_cover_s
     Returns:
         VoxCity object containing the generated 3D city model
     """
-    
+    if rectangle_vertices is not None:
+        rectangle_vertices = normalize_rectangle_vertices(rectangle_vertices)
+
     # Check if building_complementary_source was provided via kwargs (for backward compatibility)
     if building_complementary_source is None and 'building_complementary_source' in kwargs:
         building_complementary_source = kwargs.pop('building_complementary_source')
@@ -722,6 +725,9 @@ def get_voxcity(rectangle_vertices, meshsize, building_source=None, land_cover_s
 
 
 def get_voxcity_CityGML(rectangle_vertices, land_cover_source, canopy_height_source, meshsize, url_citygml=None, citygml_path=None, **kwargs):
+    if rectangle_vertices is not None:
+        rectangle_vertices = normalize_rectangle_vertices(rectangle_vertices)
+
     output_dir = kwargs.get("output_dir", "output")
     os.makedirs(output_dir, exist_ok=True)
     kwargs.pop('output_dir', None)

src/voxcity/generator/grids.py

@@ -35,6 +35,7 @@
 
 from ..utils.lc import convert_land_cover_array, get_land_cover_classes, get_source_class_descriptions
 from ..geoprocessor.io import get_gdf_from_gpkg
+from ..geoprocessor.utils import normalize_rectangle_vertices
 from ..visualizer.grids import visualize_land_cover_grid, visualize_numerical_grid
 from ..utils.logging import get_logger
 from ..errors import ProcessingError
@@ -49,6 +50,9 @@ def get_last_effective_land_cover_source():
 
 
 def get_land_cover_grid(rectangle_vertices, meshsize, source, output_dir, print_class_info=True, **kwargs):
+    if rectangle_vertices is not None:
+        rectangle_vertices = normalize_rectangle_vertices(rectangle_vertices)
+
     quiet = kwargs.get('quiet', False)
     if not quiet:
         _logger.info("Creating Land Use Land Cover grid\n ")
@@ -144,6 +148,9 @@ def get_land_cover_grid(rectangle_vertices, meshsize, source, output_dir, print_
 
 
 def get_building_height_grid(rectangle_vertices, meshsize, source, output_dir, building_gdf=None, **kwargs):
+    if rectangle_vertices is not None:
+        rectangle_vertices = normalize_rectangle_vertices(rectangle_vertices)
+
     ee_required_sources = {"Open Building 2.5D Temporal"}
     if source in ee_required_sources:
         initialize_earth_engine()
@@ -249,6 +256,9 @@ def get_building_height_grid(rectangle_vertices, meshsize, source, output_dir, b
 
 
 def get_canopy_height_grid(rectangle_vertices, meshsize, source, output_dir, **kwargs):
+    if rectangle_vertices is not None:
+        rectangle_vertices = normalize_rectangle_vertices(rectangle_vertices)
+
     quiet = kwargs.get('quiet', False)
     if not quiet:
         _logger.info("Creating Canopy Height grid\n ")
@@ -355,6 +365,9 @@ def get_canopy_height_grid(rectangle_vertices, meshsize, source, output_dir, **k
 
 
 def get_dem_grid(rectangle_vertices, meshsize, source, output_dir, **kwargs):
+    if rectangle_vertices is not None:
+        rectangle_vertices = normalize_rectangle_vertices(rectangle_vertices)
+
     quiet = kwargs.get('quiet', False)
     if not quiet:
         _logger.info("Creating Digital Elevation Model (DEM) grid\n ")