feat(3D-Texture): add 3D Texture scripts (restored from e543fd0) (#184)

* feat(3D-Texture): restore 3D Texture scripts from e543fd0; keep rest at main

* update pre-commit config

* Apply pre-commit fixes to selected 3D Texture scripts

* pre-commit correction

---------

Co-authored-by: plu <plu@ansys.com>

Author: MarinVillalobos

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
-  - repo: https://github.com/humitos/mirrors-autoflake
-    rev: v1.1
+  - repo: https://github.com/PyCQA/autoflake
+    rev: v2.2.1
     hooks:
       - id: autoflake
         args: ['-i', '--remove-all-unused-imports']

ansys_optical_automation/application/A_1_Create_stl_polynomial_surface.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Fit a 2D polynomial surface z = f(x, y) from a Speos .OPT3DMapping file,
+generate an STL mesh, and export both the STL and the polynomial model JSON.
+
+This script works standalone or can be imported by another script.
+"""
+
+import json
+import os
+
+import numpy as np
+import trimesh
+
+
+def build_design_matrix(x: np.ndarray, y: np.ndarray, order: int = 5) -> np.ndarray:
+    """
+    Build the design matrix for 2D polynomial least-squares fitting.
+
+    Parameters
+    ----------
+    x, y : ndarray
+        Normalized coordinates.
+    order : int, optional
+        Polynomial total order (default: 5).
+
+    Returns
+    -------
+    ndarray
+        Vandermonde-like matrix of shape (N, (order+1)(order+2)/2).
+    """
+    terms = []
+    for i in range(order + 1):
+        for j in range(order + 1 - i):
+            terms.append((x**i) * (y**j))
+    return np.vstack(terms).T
+
+
+def evaluate_fitted_surface(coeffs: np.ndarray, x: np.ndarray, y: np.ndarray, order: int = 5) -> np.ndarray:
+    """
+    Evaluate the fitted polynomial surface z = f(x, y).
+
+    Parameters
+    ----------
+    coeffs : ndarray
+        Polynomial coefficients.
+    x, y : ndarray
+        Normalized coordinates.
+    order : int
+        Polynomial order.
+
+    Returns
+    -------
+    ndarray
+        Evaluated z values.
+    """
+    z = np.zeros_like(x)
+    idx = 0
+    for i in range(order + 1):
+        for j in range(order + 1 - i):
+            z += coeffs[idx] * (x**i) * (y**j)
+            idx += 1
+    return z
+
+
+def create_polynomial_surface(input_file: str, output_stl: str, output_json: str, order: int = 5) -> None:
+    """
+    Fit the polynomial surface and export STL + JSON model.
+
+    Parameters
+    ----------
+    input_file : str
+        Path to the .OPT3DMapping file.
+    output_stl : str
+        Output STL file path.
+    output_json : str
+        Output polynomial model JSON path.
+    order : int, optional
+        Polynomial order (default: 5).
+    """
+    with open(input_file, "r") as f:
+        lines = f.readlines()[1:]
+
+    points = [list(map(float, line.strip().split()[:3])) for line in lines if len(line.strip().split()) >= 3]
+    points = np.array(points)
+    x_raw, y_raw, z = points[:, 0], points[:, 1], points[:, 2]
+
+    x_mean, x_std = x_raw.mean(), x_raw.std()
+    y_mean, y_std = y_raw.mean(), y_raw.std()
+    x = (x_raw - x_mean) / x_std
+    y = (y_raw - y_mean) / y_std
+
+    X_design = build_design_matrix(x, y, order)
+    coeffs, _, _, _ = np.linalg.lstsq(X_design, z, rcond=None)
+
+    x_grid_raw = np.linspace(x_raw.min(), x_raw.max(), 100)
+    y_grid_raw = np.linspace(y_raw.min(), y_raw.max(), 100)
+    xg_raw, yg_raw = np.meshgrid(x_grid_raw, y_grid_raw)
+    xg = (xg_raw - x_mean) / x_std
+    yg = (yg_raw - y_mean) / y_std
+    zg = evaluate_fitted_surface(coeffs, xg, yg, order)
+
+    vertices = np.stack([xg_raw.flatten(), yg_raw.flatten(), zg.flatten()], axis=1)
+    faces = []
+    res_x, res_y = xg.shape
+    for i in range(res_x - 1):
+        for j in range(res_y - 1):
+            idx = i * res_y + j
+            faces.append([idx, idx + 1, idx + res_y])
+            faces.append([idx + 1, idx + res_y + 1, idx + res_y])
+    mesh = trimesh.Trimesh(vertices=vertices, faces=np.array(faces))
+    mesh.export(output_stl)
+    print(f"[OK] STL exported to: {output_stl}")
+
+    model = {
+        "order": order,
+        "coeffs": coeffs.tolist(),
+        "x_mean": float(x_mean),
+        "x_std": float(x_std),
+        "y_mean": float(y_mean),
+        "y_std": float(y_std),
+        "x_min": float(x_raw.min()),
+        "x_max": float(x_raw.max()),
+        "y_min": float(y_raw.min()),
+        "y_max": float(y_raw.max()),
+    }
+
+    os.makedirs(os.path.dirname(output_json), exist_ok=True)
+    with open(output_json, "w", encoding="utf-8") as f:
+        json.dump(model, f, ensure_ascii=False, indent=2)
+    print(f"[OK] Model JSON exported to: {output_json}")
+
+
+def main():
+    """Standalone entry point."""
+
+    base_path = (
+        r"C:\Users\amarin\OneDrive - ANSYS, Inc\Articules and Trainings ACE"
+        r"\3D Texture - Light Guide\#2. Variable pitch"
+    )
+
+    input_file = base_path + r"\TL L.3D Texture.2.OPT3DMapping"
+
+    output_stl = base_path + r"\FittedSurface_Global_HighQuality.stl"
+
+    output_json = base_path + r"\FittedSurface_Model.json"
+
+    create_polynomial_surface(
+        input_file,
+        output_stl,
+        output_json,
+    )
+
+
+if __name__ == "__main__":
+    main()

ansys_optical_automation/application/A_2_Create_a_variable_pitch_from_the_polynomial_surface.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Generate a variable-pitch .OPT3DMapping file from a polynomial surface model.
+
+If the JSON model does not exist, this script will try to import and run
+`create_polynomial_surface()` from `1_1_create_stl_polynomial_surface.py`.
+
+Everything can also be executed independently (standalone).
+"""
+
+import json
+import os
+from typing import List
+from typing import Tuple
+
+import numpy as np
+
+# Try importing the fitting script
+try:
+    from A_1_Create_stl_polynomial_surface import create_polynomial_surface
+
+    print("[INFO] Successfully imported create_polynomial_surface from 1_1_create_stl_polynomial_surface.py")
+except ModuleNotFoundError as e:
+    print(f"[ERROR] Could not import Script 1: {e}")
+    print("Make sure both scripts are in the same folder or that this folder is in sys.path.")
+    raise
+
+
+# ============================== CONFIG ============================== #
+
+MODEL_JSON = (
+    r"C:\Users\amarin\OneDrive - ANSYS, Inc\Articules and Trainings ACE\3D Texture - Light Guide"
+    r"\#2. Variable pitch\FittedSurface_Model.json"
+)
+OUTPUT_MAPPING = (
+    r"C:\Users\amarin\OneDrive - ANSYS, Inc\Articules and Trainings ACE\3D Texture - Light Guide"
+    r"\#2. Variable pitch\VariablePitch.OPT3DMapping"
+)
+INPUT_MAPPING = (
+    r"C:\Users\amarin\OneDrive - ANSYS, Inc\Articules and Trainings ACE\3D Texture - Light Guide"
+    r"\#2. Variable pitch\TL L.3D Texture.2.OPT3DMapping"
+)
+OUTPUT_STL = (
+    r"C:\Users\amarin\OneDrive - ANSYS, Inc\Articules and Trainings ACE\3D Texture - Light Guide"
+    r"\#2. Variable pitch\FittedSurface_Global_HighQuality.stl"
+)
+
+PITCH_X_START = 2.0
+PITCH_X_END = 5.0
+PITCH_Y = 1.0
+INCLUDE_EDGES = True
+
+X_MIN = None
+X_MAX = None
+Y_MIN = None
+Y_MAX = None
+
+EXTRA_CONSTANTS = ["1", "0", "0", "0", "1", "0", "0.5", "0.5", "1"]
+FLOAT_FMT = ".6f"
+
+# ==================================================================== #
+
+
+def linear_pitch_x(x: float, x_min: float, x_max: float, p_start: float, p_end: float) -> float:
+    """Linear interpolation of pitch along X."""
+    if x_max == x_min:
+        return p_start
+    t = np.clip((x - x_min) / (x_max - x_min), 0.0, 1.0)
+    return p_start * (1.0 - t) + p_end * t
+
+
+def generate_points(
+    domain: Tuple[float, float, float, float], p_start: float, p_end: float, p_y: float, include_edges: bool = True
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Generate (X, Y) grid with variable X pitch and constant Y pitch.
+
+    Parameters
+    ----------
+    domain : tuple
+        (x_min, x_max, y_min, y_max)
+    p_start, p_end, p_y : float
+        Pitch configuration.
+    include_edges : bool
+        Whether to force the last row/column at the domain edge.
+
+    Returns
+    -------
+    X_pts, Y_pts : ndarray
+        Flattened arrays of all coordinates.
+    """
+    x_min, x_max, y_min, y_max = domain
+    eps = 1e-12
+    if p_start <= 0 or p_end <= 0 or p_y <= 0:
+        raise ValueError("All pitch values must be positive.")
+
+    ys = []
+    y = y_min
+    while y <= y_max + eps:
+        ys.append(min(y, y_max))
+        y += p_y
+    if include_edges and abs(ys[-1] - y_max) > 1e-9:
+        ys.append(y_max)
+
+    X_list, Y_list = [], []
+    for yy in ys:
+        x = x_min
+        row = []
+        while x <= x_max + eps:
+            row.append(min(x, x_max))
+            x += linear_pitch_x(x, x_min, x_max, p_start, p_end)
+        if include_edges and abs(row[-1] - x_max) > 1e-9:
+            row.append(x_max)
+        X_list.extend(row)
+        Y_list.extend([yy] * len(row))
+    return np.asarray(X_list), np.asarray(Y_list)
+
+
+def eval_poly2d(coeffs: np.ndarray, x_norm: np.ndarray, y_norm: np.ndarray, order: int) -> np.ndarray:
+    """Evaluate z = f(x, y) using polynomial coefficients."""
+    z = np.zeros_like(x_norm)
+    idx = 0
+    for i in range(order + 1):
+        for j in range(order + 1 - i):
+            z += coeffs[idx] * (x_norm**i) * (y_norm**j)
+            idx += 1
+    return z
+
+
+def write_opt3d_mapping(
+    path: str,
+    X: np.ndarray,
+    Y: np.ndarray,
+    Z: np.ndarray,
+    extra_constants: List[str],
+    float_fmt: str = ".6f",
+) -> None:
+    """Write the .OPT3DMapping file."""
+    if len(extra_constants) != 9:
+        raise ValueError("Exactly 9 extra constants are required.")
+    n = len(X)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    ffmt = f"{{:{float_fmt}}}"  # noqa: E231
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(f"{n}\n")
+        for x, y, z in zip(X, Y, Z):
+            formatted_values = " ".join([ffmt.format(x), ffmt.format(y), ffmt.format(z)] + extra_constants)
+            f.write(formatted_values + "\n")
+
+
+def ensure_model_json():
+    """Ensure the polynomial model JSON exists; generate it if missing."""
+    if os.path.isfile(MODEL_JSON):
+        return
+    print("[INFO] JSON not found. Running Script 1 via direct import...")
+    create_polynomial_surface(INPUT_MAPPING, OUTPUT_STL, MODEL_JSON)
+    if not os.path.isfile(MODEL_JSON):
+        raise FileNotFoundError(f"Model JSON not generated: {MODEL_JSON}")
+
+
+def main():
+    """Main entry point."""
+    ensure_model_json()
+
+    with open(MODEL_JSON, "r", encoding="utf-8") as f:
+        model = json.load(f)
+
+    order = int(model["order"])
+    coeffs = np.asarray(model["coeffs"], float)
+    x_mean, x_std = float(model["x_mean"]), float(model["x_std"])
+    y_mean, y_std = float(model["y_mean"]), float(model["y_std"])
+
+    x_min = X_MIN or float(model["x_min"])
+    x_max = X_MAX or float(model["x_max"])
+    y_min = Y_MIN or float(model["y_min"])
+    y_max = Y_MAX or float(model["y_max"])
+
+    X_pts, Y_pts = generate_points((x_min, x_max, y_min, y_max), PITCH_X_START, PITCH_X_END, PITCH_Y, INCLUDE_EDGES)
+    x_norm = (X_pts - x_mean) / x_std
+    y_norm = (Y_pts - y_mean) / y_std
+    Z_pts = eval_poly2d(coeffs, x_norm, y_norm, order)
+    write_opt3d_mapping(OUTPUT_MAPPING, X_pts, Y_pts, Z_pts, EXTRA_CONSTANTS, FLOAT_FMT)
+
+    print(f"[OK] Mapping created: {OUTPUT_MAPPING}")
+    print(f"[INFO] Total points: {len(X_pts)}")
+    print(f"[INFO] Domain X[{x_min}, {x_max}]  Y[{y_min}, {y_max}]")
+    print(f"[INFO] Pitch X: {PITCH_X_START} → {PITCH_X_END} | Pitch Y: {PITCH_Y}")
+
+
+if __name__ == "__main__":
+    main()