@pluot/core 0.1.0

package/src/viewport.ts

@@ -0,0 +1,145 @@
+
+// TODO: auto-generate these types from the Rust side: https://github.com/keller-mark/pluot/issues/133
+export type AspectRatioMode = "Ignore" | "Contain" | "Cover";
+export type AspectRatioAlignmentMode = "Center" | "Start" | "End";
+
+export type Margins = {
+  marginTop?: number;
+  marginRight?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+};
+
+export type ViewportParams = {
+  width: number;
+  height: number;
+  aspectRatioMode: AspectRatioMode;
+  aspectRatioAlignmentMode: AspectRatioAlignmentMode;
+  margins?: Margins;
+};
+
+export type Bounds = {
+  // Each value is optional.
+  // When an entire dimension is omitted (X or Y),
+  // use the current camera settings for that dimension.
+  // When a single value is omitted (e.g., xMin), ensure the resulting camera matrix keeps this boundary unchanged.
+  xMin?: number;
+  xMax?: number;
+  yMin?: number;
+  yMax?: number;
+};
+
+// Calculate the visible data range based on camera view and viewport parameters.
+export function getBounds(cameraMatrix: Float32Array, viewportParams: ViewportParams): Required<Bounds> {
+  const zoomX = cameraMatrix[0];
+  const zoomY = cameraMatrix[5];
+  const translateX = cameraMatrix[12];
+  const translateY = cameraMatrix[13];
+
+  const marginTop = viewportParams.margins?.marginTop ?? 0;
+  const marginRight = viewportParams.margins?.marginRight ?? 0;
+  const marginBottom = viewportParams.margins?.marginBottom ?? 0;
+  const marginLeft = viewportParams.margins?.marginLeft ?? 0;
+
+  const layerW = viewportParams.width - marginLeft - marginRight;
+  const layerH = viewportParams.height - marginTop - marginBottom;
+  const layerAspectRatio = layerW / layerH;
+
+  let xScale = 1.0;
+  let yScale = 1.0;
+  if (viewportParams.aspectRatioMode === "Contain") {
+    if (layerAspectRatio > 1.0) xScale = layerAspectRatio;
+    else if (layerAspectRatio < 1.0) yScale = 1.0 / layerAspectRatio;
+  } else if (viewportParams.aspectRatioMode === "Cover") {
+    if (layerAspectRatio > 1.0) yScale = 1.0 / layerAspectRatio;
+    else if (layerAspectRatio < 1.0) xScale = layerAspectRatio;
+  }
+
+  let xAlignTranslation = 0.0;
+  let yAlignTranslation = 0.0;
+  if (viewportParams.aspectRatioAlignmentMode === "Start") {
+    xAlignTranslation = xScale - 1.0;
+    yAlignTranslation = yScale - 1.0;
+  } else if (viewportParams.aspectRatioAlignmentMode === "End") {
+    xAlignTranslation = 1.0 - xScale;
+    yAlignTranslation = 1.0 - yScale;
+  }
+
+  const xAdj = xScale - 1.0;
+  const yAdj = yScale - 1.0;
+
+  const xMin = ((-translateX - 1.0 - xAdj + xAlignTranslation) / zoomX + 1.0) / 2.0;
+  const xMax = ((-translateX + 1.0 + xAdj + xAlignTranslation) / zoomX + 1.0) / 2.0;
+  const yMin = ((-translateY - 1.0 - yAdj + yAlignTranslation) / zoomY + 1.0) / 2.0;
+  const yMax = ((-translateY + 1.0 + yAdj + yAlignTranslation) / zoomY + 1.0) / 2.0;
+
+  return { xMin, xMax, yMin, yMax };
+}
+
+// Given data bounds, compute the corresponding camera matrix.
+// Missing bound values are filled in from prevCameraMatrix.
+export function getCameraMatrixFromBounds(bounds: Bounds, prevCameraMatrix: Float32Array, viewportParams: ViewportParams): Float32Array {
+  // Fill in missing bounds from the previous camera matrix.
+  const currentBounds = getBounds(prevCameraMatrix, viewportParams);
+  const xMin = bounds.xMin ?? currentBounds.xMin;
+  const xMax = bounds.xMax ?? currentBounds.xMax;
+  const yMin = bounds.yMin ?? currentBounds.yMin;
+  const yMax = bounds.yMax ?? currentBounds.yMax;
+
+  const marginTop = viewportParams.margins?.marginTop ?? 0;
+  const marginRight = viewportParams.margins?.marginRight ?? 0;
+  const marginBottom = viewportParams.margins?.marginBottom ?? 0;
+  const marginLeft = viewportParams.margins?.marginLeft ?? 0;
+
+  const layerW = viewportParams.width - marginLeft - marginRight;
+  const layerH = viewportParams.height - marginTop - marginBottom;
+  const layerAspectRatio = layerW / layerH;
+
+  let xScale = 1.0;
+  let yScale = 1.0;
+  if (viewportParams.aspectRatioMode === "Contain") {
+    if (layerAspectRatio > 1.0) xScale = layerAspectRatio;
+    else if (layerAspectRatio < 1.0) yScale = 1.0 / layerAspectRatio;
+  } else if (viewportParams.aspectRatioMode === "Cover") {
+    if (layerAspectRatio > 1.0) yScale = 1.0 / layerAspectRatio;
+    else if (layerAspectRatio < 1.0) xScale = layerAspectRatio;
+  }
+
+  let xAlignTranslation = 0.0;
+  let yAlignTranslation = 0.0;
+  if (viewportParams.aspectRatioAlignmentMode === "Start") {
+    xAlignTranslation = xScale - 1.0;
+    yAlignTranslation = yScale - 1.0;
+  } else if (viewportParams.aspectRatioAlignmentMode === "End") {
+    xAlignTranslation = 1.0 - xScale;
+    yAlignTranslation = 1.0 - yScale;
+  }
+
+  const xAdj = xScale - 1.0;
+  const yAdj = yScale - 1.0;
+
+  const xRange = xMax - xMin;
+  const yRange = yMax - yMin;
+
+  let zoomX = (1.0 + xAdj) / xRange;
+  let zoomY = (1.0 + yAdj) / yRange;
+
+  // When aspect ratio is ignored, zoom each axis independently.
+  // Otherwise take the minimum so all requested data fits within the viewport.
+  if (viewportParams.aspectRatioMode !== "Ignore") {
+    zoomX = zoomY = Math.min(zoomX, zoomY);
+  }
+
+  // Invert the getBounds translation equations:
+  //   min + max = (-translate + align) / zoom + 1.0
+  // So: translate = align - zoom * ((min + max) - 1.0)
+  const translateX = xAlignTranslation - zoomX * ((xMin + xMax) - 1.0);
+  const translateY = yAlignTranslation - zoomY * ((yMin + yMax) - 1.0);
+
+  return new Float32Array([
+    zoomX, 0.0,   0.0, 0.0,
+    0.0,   zoomY, 0.0, 0.0,
+    0.0,   0.0,   1.0, 0.0,
+    translateX, translateY, 0.0, 1.0,
+  ]);
+}