@world-engines/spatial-authoring 0.1.0-alpha.0

package/dist/road-parcels.d.ts

@@ -0,0 +1,83 @@
+import type { CityDescriptorV1, Point2D, ProceduralParcel } from "./procedural-city.js";
+/** 来自 terrain-roads-v1 的单个道路采样点，单位为米。 */
+export interface RoadParcelPoint extends Point2D {
+    readonly z: number;
+}
+export type RoadParcelSegmentKind = "surface" | "bridge" | "tunnel";
+export type RoadParcelRoadKind = "intercity" | "arterial" | "local";
+export type RoadParcelRoadClass = "street" | "motorway";
+/**
+ * `id` 由道路 id 与 segment 下标隐式组成；不要把输入数组顺序作为 identity。
+ * bridge/tunnel 仅供渲染和通行，不能围出地面 block。
+ */
+export interface RoadParcelSegment {
+    readonly kind: RoadParcelSegmentKind;
+    readonly points: readonly RoadParcelPoint[];
+}
+export interface RoadParcelRoad {
+    readonly id: string;
+    /** terrain-roads-v1 必填道路等级；缺失/未知等级绝不可被当作可建街道。 */
+    readonly kind: RoadParcelRoadKind;
+    /** motorway 是禁建走廊，即使错误标有 cityId 也不可围 block。 */
+    readonly roadClass?: RoadParcelRoadClass;
+    readonly cityId?: string;
+    readonly widthMeters: number;
+    readonly points?: readonly RoadParcelPoint[];
+    readonly segments: readonly RoadParcelSegment[];
+}
+export interface RoadParcelTerrainGrid {
+    readonly width: number;
+    readonly height: number;
+    readonly widthMeters: number;
+    readonly heightMeters: number;
+    readonly originX: number;
+    readonly originY: number;
+    /** 行优先；单位米，和 WASM city bbox sampler 的输出一致。 */
+    readonly elevationsMeters: readonly number[];
+    /** 行优先；true/非零代表水面，false/零代表陆地。 */
+    readonly waterMask: readonly (boolean | number)[];
+}
+/** city extent adapter 的权威可建边界；unbuildable 明确禁止任何地块回退。 */
+export interface RoadParcelBoundary {
+    readonly status: "bounded" | "unbuildable";
+    readonly points: readonly Point2D[];
+}
+export interface RoadParcelSettings {
+    /** 单个地块的最大面积；超出时按稳定语义切分。 */
+    readonly maxFaceAreaMeters?: number;
+    /** 从道路中心线额外退让的距离；道路半宽始终会计入。 */
+    readonly setbackMeters?: number;
+    /** terrain 四邻域允许的最大坡度（rise/run）。 */
+    readonly maxSlope?: number;
+    /** 防止退让、切分后产生不值得消费的碎片。 */
+    readonly minParcelAreaMeters?: number;
+    /** shape-filled-v10 的方向无关最长/最短方向比上限。 */
+    readonly maxAspectRatio?: number;
+    /** shape-filled-v10 的方向无关最短方向尺寸下限（米）。 */
+    readonly minShortSideMeters?: number;
+}
+export interface RoadParcelInput {
+    /** 缺省和 legacy-v6 保持既有地块切分；新 profile 必须显式选择。 */
+    readonly algorithm?: "legacy-v6" | "structured-v8" | "frontage-balanced-v9" | "shape-filled-v10";
+    readonly roads: readonly RoadParcelRoad[];
+    /** WASM cityLayouts.boundary 的 canonical world-meter、CCW、非闭合城市可建边界。 */
+    readonly boundary?: RoadParcelBoundary;
+    /** 缺失 terrain 时不生成地块，避免把未知水面或陡坡伪装成可建地。 */
+    readonly terrain?: RoadParcelTerrainGrid;
+    readonly settings?: RoadParcelSettings;
+}
+export interface RoadParcelLayout {
+    readonly parcels: readonly ProceduralParcel[];
+}
+/**
+ * 边界 touch 可共存；只要外轮廓有正面积交集即为冲突。
+ * 绝不能以内部 building safe bounds 作早退，因为两个外轮廓可相交而两个 safe square 分离。
+ */
+export declare function roadParcelPolygonsOverlapWithArea(a: readonly Point2D[], b: readonly Point2D[]): boolean;
+/** 固定 city bbox grid 的最近点采样；水和过陡的 cell 均不可建。 */
+export declare function sampleRoadParcelTerrain(grid: RoadParcelTerrainGrid, candidate: Point2D, maxSlope?: number): boolean;
+/**
+ * 从 surface road 的 planar faces 生成可重建的真实地块。缺少可采样 terrain 时有意返回空，
+ * 而非退回矩形棋盘或猜测水面；建筑需在角色进入 gate 后再以 parcel.bounds 生成。
+ */
+export declare function generateRoadParcels(worldSeed: number, city: CityDescriptorV1, input: RoadParcelInput): RoadParcelLayout;