Metadata-Version: 2.2
Name: meodin
Version: 0.1.8
Summary: Optical Design Integrated Network
Author: Sebastian Gedeon
Author-email: sebastian.gedeon@gmail.com
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pymssql
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

ODIN is a demo Python package for optical engineers.
We believe in a straightforward path to great design and tolerancing.
Let the best wavefront win😄

## Requirements

- Python 3.x, ZOSAPI, NumPy, clr, os, winreg, random

# Math Module

## Interferometry Math Utilities

 Lightweight Python helpers for common interferometry conversions.
 Convert surface irregularity and optical power between fringes,
 millimeters, and radius of curvature.

## Features

 - Irregularity conversion: fringes ↔ millimeters
 - Optical power conversion: fringes ↔ millimeters
 - Supports concave (CC) and convex (CX) surfaces
 - NumPy-only dependency
 - Simple random value generator for simulation/testing

## Main Class
```Python
Math()
 ```
- Main interface for using Math functions.

## Functions

```Python
irrFrToMm(fringes, wavelength_nm)
```
- Convert surface irregularity from fringes to millimeters.
```Python
irrMmToFr(irregularity_mm, wavelength_nm)
```
- Convert surface irregularity from millimeters to fringes.
```Python
powFrToMm(diameter_mm, nominal_radius_mm, surface_type, fringes, wavelength_nm)
```
- Convert power in fringes to corrected radius in millimeters.
```Python
powMmToFr(diameter_mm, nominal_radius_mm, surface_type, power_mm, wavelength_nm)
```
- Convert power in millimeters to fringes.
```Python
randomValue(distribution="uniform")
```
- Generate a random value between -1 and 1.
    - Distributions: uniform, gauss, parabolic

# ZOSpy Module

A demo Python wrapper for Zemax OpticStudio (ZOS-API)

## ZOSpy – OpticStudio Automation Utilities

Lightweight Python interface for connecting to Zemax OpticStudio,
manipulating lens data, merit functions, and running tolerancing
analyses via ZOS-API.

## Features

- Offline ZMX file read/write/edit without OpticStudio
- Connect to OpticStudio (Interactive or Standalone)
- Open, save, and modify ZMX/ZOS files
- Lens Data Editor (LDE) surface and parameter control
- Merit Function Editor (MFE) access
- Local optimization control
- Monte Carlo tolerancing utilities

## Main Class
```Python
ZOSpy()
 ```
- Main interface for connecting to and controlling OpticStudio.

## File Handling
```Python
readOfflineZmx(pathToZmx)
```
- Read a .zmx file as text into memory.
```Python
writeOfflineZmx(pathToZmxWithNewName)
```
- Write modified offline .zmx content to file.
```Python
openFile(path)
```
- Open a ZMX or ZOS file in OpticStudio.
```Python
saveFile()
```
- Save the current system.
```Python
saveAsFile(pathWithName)
```
- Save the system under a new name.

## Connections
```Python
connectOS()
```
- Connect via Interactive Extension.
```Python
connectOSSA()
```
- Connect via Standalone Application.
```Python
disconnectOS()
```
- Close OpticStudio and release the connection.

## OfflineLDE
```Python
OfflineLDE.getParameter(surface, parameter)
```
- Read a surface parameter from offline ZMX text.
```Python
OfflineLDE.setParameter(surface, parameter, value)
```
- Modify a surface parameter in offline ZMX text.

## LDE (Lens Data Editor)
```Python
LDE.getSurfaceByComment(comment)
```
- Find a surface index by comment.
```Python
LDE.addSurfaceAfter(surface)
LDE.addSurfaceBefore(surface)
```
- Add new surfaces relative to an existing one.
```Python
LDE.removeSurfaces(first_surface, last_surface)
```
- Remove a range of surfaces.
```Python
LDE.setSurfaceType(surface, type)
```
- Change the surface type.
```Python
LDE.setParameter(surface, parameter, value)
```
- Set a surface parameter.
```Python
LDE.getParameter(surface, parameter)
```
- Get a surface parameter value.
```Python
LDE.ignoreSurface(surface, bool)
```
- Enable or ignore a surface.
```Python
LDE.setUiUpdate(bool)
```
- Enable or disable live UI updates.
```Python
LDE.removeAllVariable()
```
- Remove all variables from the system.
```Python
LDE.setCoordinateBreakToElement(surface_1, surface_2, color)
```
- Group surfaces into an element using coordinate breaks.

## MFE (Merit Function Editor)
```Python
MFE.loadMeritFunction(path)
```
- Load a merit function file.
```Python
MFE.calculateMeritFunction()
```
- alculate the current merit function.
```Python
MFE.getTarget(line)
MFE.setTarget(line, target)
```
- Get or set merit function targets.
```Python
MFE.getWeight(line)
MFE.setWeight(line, weight)
```
- Get or set merit function weights.
```Python
MFE.getValue(line)
```
- Read a merit function value.

## TDE (Tolerance Data Editor)
```Python
TDE.loadTDE(path)
```

## Tolerancing
```Python
Tolerancing.getMonteCarlo()
```
- Run a single Monte Carlo tolerancing analysis.
```Python
Tolerancing.runMonteCarlos(cores, ScriptIndex, NumberOfRuns, NumberToSave)
```
- Run multiple Monte Carlo simulations.
```Python
Tolerancing.getData(column)
```
- Extract a column of Monte Carlo result data.

## Analysis
```Python
Analysis.getUnitNormalizedSensitivityMatrix(input_array)
```
- Calculate the sensitivity of MFE operands relative to specific parameter perturbations and record nominal states.
```Python
Analysis.plotSensitivityMatrix(sensitivity_matrix, input_array)
```
- Generate a heatmap visualization of the sensitivity data with dynamic scaling and parameter labeling.


## Database Module

### SQL Server Database Utilities

Lightweight Python helper class for connecting to and interacting
with a Microsoft SQL Server database.
Provides simple methods for connection handling, table inspection,
and filtered data retrieval.
Uses a config.ini file for credential management.

### Features

- Connect / disconnect using config file
- List all database tables
- Show table structure (columns, types, length)
- Display full table content
- Filtered data retrieval (pn, sn)
- Table whitelist for basic SQL injection protection
- Uses pymssql

### Main Class

```Python
Database()
```
- Main interface for managing database operations.

### Functions

```Python
connect(config_path, password=None)
```
- Connect to the database using a config.ini file.
- Internal Access Only: This function is password-protected and intended for use by authorized colleagues only.

```Python
disconnect()
```
- Close the active database connection.

```Python
listTables()
```
- List all base tables in the database.

```Python
showTableStructure(table_name)
```
- Display column structure of a selected table.

```Python
showTableData(table_name)
```
- Display all rows from a selected table.

```Python
getData(table, pn, sn)
```
- Retrieve rows filtered by part number (pn) and serial number (sn).
- Table must be in the allowed whitelist.

```Python
getThicknessData(pn, sn)
```
- Retrieve rows from the thickness table filtered by part number (pn) and serial number (sn).
- Automatically searches within the [LentsTrace].[dbo].[thickness] path.
- Results are sorted by [datetime] in descending order.

```Python
getRadiusData(pn, sn, side)
```
- Retrieve rows from the Radii table filtered by part number (pn), serial number (sn), and side.
- Automatically searches within the [LentsTrace].[dbo].[Radii] path.
- Results are sorted by [datetime] in descending order.

```Python
getOwiData(pn, sn, side)
```
- Retrieve rows from the OWI table filtered by part number (pn), serial number (sn), and side.
- The side parameter is matched against the strana column in the database.
- Results are sorted by the measurement timestamp [mereno] in descending order.

### Example config.ini

```ini
[database]
server = YOUR_SERVER
database = YOUR_DATABASE
username = YOUR_USERNAME
password = YOUR_PASSWORD
```

# Zernike Module

## Interferometric Zernike Utilities

Comprehensive Python interface for working with Fringe Zernike polynomials (Z1–Z37) on 2D interferometric measurement datasets.
It supports loading Zygo MetroPro .datx data files and XML circular .mask files, defining circular apertures, fitting Zernike coefficients, removing statistical outliers, and calculating surface metrics such as Peak-to-Valley (PV) and Root Mean Square (RMS).

## Features

- Full support for Fringe Zernike terms Z1 through Z37
- Native data loading for Zygo Mx HDF5 (.datx) surface maps
- Circular aperture parsing and mapping for Zygo Mx (.mask) profiles
- Robust outlier and surrounding-neighborhood pixel removal via Median Absolute Deviation (MAD)
- Linear least-squares Zernike coefficient fitting over active aperture regions
- Calculation of surface quality metrics (PV and RMS)
- Surface rendering with aperture overlays, customizable color maps, and display zoom limits

## Main Class

```Python
ZernikeEvaluator(res_x, res_y, x_range, y_range)
```
- Main evaluation engine for managing grid dimensions, aperture masks, and Zernike calculations across a 2D interferometric surface map.

## File & Mask Setup

```Python
ZernikeEvaluator.load_datx_file(filepath)
```
- Load surface map data from a Zygo MetroPro HDF5 (.datx) file and auto-resize grid dimensions if necessary.

```Python
ZernikeEvaluator.load_masx_file(filepath)
```
- Load and map a circular aperture definition from an XML (.mask) profile to spatial coordinates.

```Python
ZernikeEvaluator.add_circular_aperture(center_x, center_y, radius)
```
- Manually set a circular clear aperture mask using center coordinates and radius.

## Surface Modification & Analysis

```Python
ZernikeEvaluator.add_fringe_zernike_sag(term_id, height)
```
- Evaluate a specific Fringe Zernike polynomial (Z1 through Z37) and add its sag height contribution to the surface matrix.

```Python
ZernikeEvaluator.fit_fringe_zernike_coefficient(term_id)
```
- Fit a specified Zernike coefficient (Z1 to Z37) to active surface data using linear least-squares.

```Python
ZernikeEvaluator.remove_outliers_and_neighborhood(threshold_sigma=5.0, neighborhood_pixels=2)
```
- Identify extreme statistical outliers inside the active aperture using MAD and clear them along with their surrounding pixel neighborhood.

## Metrics & Spatial Bounds

```Python
ZernikeEvaluator.getPV()
```
- Calculate the Peak-to-Valley (PV) surface error range across the active aperture.

```Python
ZernikeEvaluator.getRMS()
```
- Calculate the Root Mean Square (RMS) error across the active aperture.

```Python
ZernikeEvaluator.get_data_bounding_box(padding_pixels=10)
```
- Compute spatial bounding box limits (xmin, xmax, ymin, ymax) restricted to valid (non-NaN) data pixels with optional border padding.

## Visualization

```Python
ZernikeEvaluator.render_surface(title="Zernike Surface Profile", cmap="jet", zoom_limits=None)
```
- Display a Matplotlib 2D plot of active surface data with a colorbar, clear aperture mask overlay, and optional zoom boundary limits.
