NODEDC_DESIGN_GUIDELINE/apps/catalog/src/mapSectorGrid.d.mts

export type LocalBounds = { west: number; east: number; south: number; north: number };
export type LocalCenter = { eastMeters: number; northMeters: number };
export type GeodeticBounds = { west: number; east: number; south: number; north: number };
export type GeodeticCenter = { longitude: number; latitude: number };

export type LocalGridDefinition = {
  lod: number;
  originLatitude: number;
  originLongitude: number;
  stepMeters: number;
};

export type LocalHierarchyDefinition = LocalGridDefinition & { tileSizeMeters: number };
export type LocalVolumeDefinition = LocalGridDefinition & {
  altitudeFloorMeters?: number;
  altitudeCeilingMeters?: number;
  /** @deprecated Use altitudeFloorMeters. */
  altitudeOriginMeters?: number;
  altitudeBandMeters: number;
};

export type LocalSectorAddress = {
  family: "local-enu";
  lod: number;
  eastIndex: number;
  northIndex: number;
  id: string;
};

export type LocalMajorTileAddress = {
  family: "local-enu-major";
  lod: number;
  eastIndex: number;
  northIndex: number;
  minorPerSide: number;
  id: string;
};

export type LocalVolumeAddress = {
  family: "local-enu-volume";
  lod: number;
  eastIndex: number;
  northIndex: number;
  bandIndex: number;
  altitudeFloorMeters: number;
  altitudeCeilingMeters: number;
  altitudeBandMeters: number;
  id: string;
};

export type GraticuleDefinition = { lod: number; stepDegrees: number };
export type GraticuleHierarchyDefinition = GraticuleDefinition & { majorStepDegrees: number };
export type GraticuleSectorAddress = {
  family: "wgs84-graticule";
  lod: number;
  longitudeIndex: number;
  latitudeIndex: number;
  id: string;
};

export type GraticuleMajorTileAddress = {
  family: "wgs84-graticule-major";
  lod: number;
  longitudeIndex: number;
  latitudeIndex: number;
  minorPerSide: number;
  id: string;
};

export type AddressDetail<Address, Bounds, Center> = {
  address: Address;
  bounds: Bounds;
  center: Center;
  areaSquareMeters: number;
};

export type LocalSectorDetail = AddressDetail<LocalSectorAddress, LocalBounds, LocalCenter>;
export type LocalMajorTileDetail = AddressDetail<LocalMajorTileAddress, LocalBounds, LocalCenter>;
export type GraticuleSectorDetail = AddressDetail<GraticuleSectorAddress, GeodeticBounds, GeodeticCenter>;
export type GraticuleMajorTileDetail = AddressDetail<GraticuleMajorTileAddress, GeodeticBounds, GeodeticCenter>;

export type LocalSectorSummary = {
  id: string;
  address: LocalSectorAddress;
  family: "local-enu";
  lod: number;
  label: string;
  indices: { eastIndex: number; northIndex: number };
  bounds: LocalBounds;
  center: LocalCenter;
  areaSquareMeters: number;
  neighbors: Record<"north" | "east" | "south" | "west", LocalSectorDetail>;
  majorTile: LocalMajorTileSummary | null;
  parentMajorTile: LocalMajorTileSummary | null;
};

export type LocalMajorTileSummary = {
  id: string;
  address: LocalMajorTileAddress;
  family: "local-enu-major";
  lod: number;
  label: string;
  indices: { eastIndex: number; northIndex: number };
  minorPerSide: number;
  childCount: number;
  bounds: LocalBounds;
  center: LocalCenter;
  areaSquareMeters: number;
  neighbors: Record<"north" | "east" | "south" | "west", LocalMajorTileDetail>;
};

export type LocalVolumeBounds = LocalBounds & {
  altitudeFloorMeters: number;
  altitudeCeilingMeters: number;
};

export type LocalVolumeSummary = {
  id: string;
  address: LocalVolumeAddress;
  family: "local-enu-volume";
  lod: number;
  label: string;
  indices: { eastIndex: number; northIndex: number; bandIndex: number };
  bounds: LocalVolumeBounds;
  center: LocalCenter & { altitudeMeters: number };
  footprintAreaSquareMeters: number;
  volumeCubicMeters: number;
};

export type GraticuleSectorSummary = {
  id: string;
  address: GraticuleSectorAddress;
  family: "wgs84-graticule";
  lod: number;
  label: string;
  indices: { longitudeIndex: number; latitudeIndex: number };
  bounds: GeodeticBounds;
  center: GeodeticCenter;
  areaSquareMeters: number;
  neighbors: Record<"north" | "east" | "south" | "west", GraticuleSectorDetail | null>;
  majorTile: GraticuleMajorTileSummary | null;
  parentMajorTile: GraticuleMajorTileSummary | null;
};

export type GraticuleMajorTileSummary = {
  id: string;
  address: GraticuleMajorTileAddress;
  family: "wgs84-graticule-major";
  lod: number;
  label: string;
  indices: { longitudeIndex: number; latitudeIndex: number };
  minorPerSide: number;
  childCount: number;
  bounds: GeodeticBounds;
  center: GeodeticCenter;
  areaSquareMeters: number;
  neighbors: Record<"north" | "east" | "south" | "west", GraticuleMajorTileDetail | null>;
};

export const MAX_LOCAL_GRID_INDEX: number;
export const MAX_GRID_CHILD_PAGE_SIZE: number;

export type GridChildPage = { offset?: number; limit?: number };

export function normalizeLongitudeDegrees(value: number): number;
export function fixedGridOrigin(settings: { gridCenterLatitude?: number; gridCenterLongitude?: number }): { latitude: number; longitude: number };

// Existing horizontal sector IDs are intentionally unchanged in v2.
export function localSectorId(definition: LocalGridDefinition, eastIndex: number, northIndex: number): string;
export function localSectorAt(point: { eastMeters: number; northMeters: number }, definition: LocalGridDefinition): LocalSectorAddress;
export function localSectorBounds(address: LocalSectorAddress, stepMeters: number): LocalBounds;
export function localSectorNeighbors(address: LocalSectorAddress, definition: LocalGridDefinition): Record<"north" | "east" | "south" | "west", LocalSectorAddress>;
export function localParentSector(address: LocalSectorAddress, childStepMeters: number, parentDefinition: LocalGridDefinition): LocalSectorAddress;
export function localSectorCenter(address: LocalSectorAddress, stepMeters: number): LocalCenter;
export function localSectorAreaSquareMeters(address: LocalSectorAddress, stepMeters: number): number;
export function localSectorSummary(
  address: LocalSectorAddress,
  definition: LocalGridDefinition & { tileSizeMeters?: number },
): LocalSectorSummary;

export function localMajorTileId(definition: LocalHierarchyDefinition, eastIndex: number, northIndex: number): string;
export function localMajorTileAt(point: { eastMeters: number; northMeters: number }, definition: LocalHierarchyDefinition): LocalMajorTileAddress;
export function localMajorTileBounds(address: LocalMajorTileAddress, tileSizeMeters: number): LocalBounds;
export function localMajorTileForSector(address: LocalSectorAddress, definition: LocalHierarchyDefinition): LocalMajorTileAddress;
export function localMajorTileChildren(
  address: LocalMajorTileAddress,
  definition: LocalHierarchyDefinition,
  options?: GridChildPage,
): LocalSectorAddress[];
export function localMajorTileNeighbors(address: LocalMajorTileAddress, definition: LocalHierarchyDefinition): Record<"north" | "east" | "south" | "west", LocalMajorTileAddress>;
export function isLocalMajorLineIndex(lineIndex: number, definition: LocalHierarchyDefinition): boolean;
export function localMajorTileCenter(address: LocalMajorTileAddress, tileSizeMeters: number): LocalCenter;
export function localMajorTileAreaSquareMeters(address: LocalMajorTileAddress, tileSizeMeters: number): number;
export function localMajorTileSummary(address: LocalMajorTileAddress, definition: LocalHierarchyDefinition): LocalMajorTileSummary;

export function localVolumeId(definition: LocalVolumeDefinition, eastIndex: number, northIndex: number, bandIndex: number): string;
export function localVolumeAt(
  point: { eastMeters: number; northMeters: number; altitudeMeters: number },
  definition: LocalVolumeDefinition,
): LocalVolumeAddress | null;
export function localVolumeBounds(address: LocalVolumeAddress, definition: LocalVolumeDefinition): LocalVolumeBounds;
export function localVolumeNeighbors(address: LocalVolumeAddress, definition: LocalVolumeDefinition): {
  north: LocalVolumeAddress;
  east: LocalVolumeAddress;
  south: LocalVolumeAddress;
  west: LocalVolumeAddress;
  above: LocalVolumeAddress | null;
  below: LocalVolumeAddress | null;
};
export function localVolumeCenter(address: LocalVolumeAddress, definition: LocalVolumeDefinition): LocalCenter & { altitudeMeters: number };
export function localVolumeSummary(address: LocalVolumeAddress, definition: LocalVolumeDefinition): LocalVolumeSummary;

export function localGridPlan(input: { stepMeters: number; radiusMeters: number; maximumMarkers?: number }): {
  stepMeters: number;
  radiusMeters: number;
  requestedRadiusMeters: number;
  clipped: boolean;
  maximumIndex: number;
  markerStride: number;
  lines: Array<{ index: number; offsetMeters: number; extentMeters: number }>;
};

// Existing horizontal graticule IDs are intentionally unchanged in v2.
export function graticuleSectorId(definition: GraticuleDefinition, longitudeIndex: number, latitudeIndex: number): string;
export function graticuleSectorAt(point: { longitude: number; latitude: number }, definition: GraticuleDefinition): GraticuleSectorAddress;
export function graticuleSectorBounds(address: GraticuleSectorAddress, stepDegrees: number): GeodeticBounds;
export function graticuleSectorNeighbors(address: GraticuleSectorAddress, definition: GraticuleDefinition): Record<"north" | "east" | "south" | "west", GraticuleSectorAddress | null>;
export function graticuleSectorCenter(address: GraticuleSectorAddress, stepDegrees: number): GeodeticCenter;
export function graticuleSectorAreaSquareMeters(address: GraticuleSectorAddress, stepDegrees: number): number;
export function graticuleSectorSummary(
  address: GraticuleSectorAddress,
  definition: GraticuleDefinition & { majorStepDegrees?: number },
): GraticuleSectorSummary;

export function graticuleMajorTileId(definition: GraticuleHierarchyDefinition, longitudeIndex: number, latitudeIndex: number): string;
export function graticuleMajorTileAt(point: { longitude: number; latitude: number }, definition: GraticuleHierarchyDefinition): GraticuleMajorTileAddress;
export function graticuleMajorTileBounds(address: GraticuleMajorTileAddress, majorStepDegrees: number): GeodeticBounds;
export function graticuleMajorTileForSector(address: GraticuleSectorAddress, definition: GraticuleHierarchyDefinition): GraticuleMajorTileAddress;
export function graticuleMajorTileChildren(
  address: GraticuleMajorTileAddress,
  definition: GraticuleHierarchyDefinition,
  options?: GridChildPage,
): GraticuleSectorAddress[];
export function graticuleMajorTileNeighbors(address: GraticuleMajorTileAddress, definition: GraticuleHierarchyDefinition): Record<"north" | "east" | "south" | "west", GraticuleMajorTileAddress | null>;
export function isGraticuleMajorLineIndex(lineIndex: number, definition: GraticuleHierarchyDefinition): boolean;
export function isGraticuleMajorLineValue(valueDegrees: number, definition: GraticuleHierarchyDefinition): boolean;
export function graticuleMajorTileCenter(address: GraticuleMajorTileAddress, majorStepDegrees: number): GeodeticCenter;
export function graticuleMajorTileAreaSquareMeters(address: GraticuleMajorTileAddress, majorStepDegrees: number): number;
export function graticuleMajorTileSummary(address: GraticuleMajorTileAddress, definition: GraticuleHierarchyDefinition): GraticuleMajorTileSummary;
export function geodeticRectangleAreaSquareMeters(bounds: GeodeticBounds): number;

export function splitLongitudeRange(west: number, east: number): Array<{ west: number; east: number }>;
export function alignedGridValues(minimum: number, maximum: number, step: number, options?: { includeMaximum?: boolean }): number[];
export function boundedAngularParts(start: number, end: number, maximumSpanDegrees?: number): Array<{ start: number; end: number }>;
export function graticuleGranularity(stepDegrees: number, clampToGround: boolean): number;
export function graticuleLinePlan(input: {
  south: number;
  north: number;
  longitudeIntervals: Array<{ west: number; east: number }>;
  stepDegrees: number;
}): {
  stepDegrees: number;
  south: number;
  north: number;
  longitudeIntervals: Array<{ west: number; east: number }>;
  parallels: number[];
  meridians: Array<{ longitude: number; interval: { west: number; east: number } }>;
};