openLens

An interactive optical lens design and simulation tool for single glass lens elements

---

What is openlens?

openlens is a desktop application for designing and analyzing glass optical lenses. Whether you're a student learning optics, an engineer designing optical systems, or a hobbyist exploring lens physics, openlens provides an intuitive interface to:

• Design optical lenses with precise physical parameters
• Calculate optical properties using the lensmaker's equation
• Experiment with different glass materials and geometries
• Store and manage your lens designs
• Visualize how lens parameters affect focal length and optical power

Features

Optical Design

• Define lens geometry: radii of curvature, thickness, diameter
• Select from common optical materials (BK7, Fused Silica, Crown Glass, etc.)
• Support for all lens types: Biconvex, Biconcave, Plano-Convex, Plano-Concave, Meniscus

Ray Tracing Simulation

• Visual ray tracing through lens elements
• Snell's law physics simulation
• Parallel rays (collimated beam) and point source modes
• Automatic focal point detection and display
• Interactive controls for number of rays and angles

Aberrations Analysis

• Calculate five primary (Seidel) aberrations
• Chromatic aberration with material-specific Abbe numbers
• Spherical aberration, coma, astigmatism, field curvature, distortion
• Automatic quality assessment and scoring
• Diffraction-limited resolution (Airy disk)
• Numerical aperture and F-number calculations
• Professional-grade optical analysis

3D Visualization

• Interactive 3D rendering of lens cross-section
• Visualize spherical surfaces and lens geometry
• Real-time ray path visualization

Professional Capabilities

• Optimization: Global search (Simulated Annealing) and Desensitization optimization for manufacturability.
• Tolerancing: Monte Carlo analysis and Inverse Sensitivity to predict manufacturing yields.
• Advanced Analysis: Ghost analysis (stray light), Physical Optics (Beam Synthesis Propagation), and Diffraction (PSF/MTF).
• Interoperability: Export designs to STL (3D printing) and ISO 10110 drawings (SVG).

---

Installation

Prerequisites

Core Requirements:

• Python 3.7 or higher
• PySide6 ≥ 6.2 (GUI framework - installed via pip)
• X11 display server (Linux) or native display (Windows/Mac)

Recommended Dependencies:

Package	Version	Features Enabled
numpy	≥1.19.0	Numerical operations, ray tracing, STL export
matplotlib	≥3.3.0	Plots, analysis dialogs

Optional Dependencies:

Package	Version	Features Enabled
scipy	≥1.5.0	Advanced diffraction calculations, image simulation
Pillow (PIL)	≥8.0.0	Image loading for image simulator

Note: The recommended/optional dependencies are gracefully handled - the application will run with reduced functionality if they are not installed.

Installing PySide6

pip install PySide6

(or simply pip install -r requirements.txt)

Method 1: Automated Setup (Recommended)

Use the provided setup script to automatically create and configure the virtual environment:

Linux/macOS:

./setup_venv.sh
source venv/bin/activate

# Install optional dependencies for full features (recommended)
pip install matplotlib numpy

# For advanced features (diffraction, image simulation)
pip install scipy Pillow

Windows:

setup_venv.bat
venv\Scripts\activate

REM Install optional dependencies for full features (recommended)
pip install matplotlib numpy

REM For advanced features (diffraction, image simulation)
pip install scipy Pillow

The script will:

• Check Python installation
• Create virtual environment
• Display activation instructions

What works without optional dependencies:

• ✅ All core lens calculations (focal length, optical power)
• ✅ Lens creation, editing, and management
• ✅ GUI interface (PySide6)
• ✅ Data persistence (SQLite)
• ⚠️ Ray tracing and analysis plots need numpy/matplotlib
• ❌ Advanced diffraction calculations with Bessel functions (requires scipy)
• ❌ Image simulation (requires scipy + Pillow)

Method 2: Manual Setup

1. Clone or download the repository:

   git clone <repository-url>
   cd openLens

2. Set up virtual environment (recommended):

   # Create virtual environment
   python3 -m venv venv
   
   # Activate virtual environment
   # On Linux/macOS:
   source venv/bin/activate
   
   # On Windows:
   venv\Scripts\activate

3. Install optional dependencies:

   For full features (recommended):

   pip install matplotlib numpy

   For advanced features:

   pip install scipy Pillow

   Or install all optional dependencies:

   pip install -r requirements.txt

   Note: The application works without these, with features gracefully disabled.

4. Verify Python and PySide6:

   python3 --version
   # Should show Python 3.7 or higher
   
   python3 -c "import PySide6; print('PySide6 available')"

5. Run the application:

   # GUI version (recommended)
   python3 openlens.py
   
   # OR CLI version
   python3 -m src.lens_editor

6. When done, deactivate virtual environment (if used):

   deactivate

---

Lens Properties Explained

Physical Properties

Property	Description	Units	Sign Convention
Radius of Curvature 1 (R1)	Front surface radius	mm	Positive = convex, Negative = concave
Radius of Curvature 2 (R2)	Back surface radius	mm	Positive = convex, Negative = concave
Center Thickness	Thickness at optical center	mm	Always positive
Diameter	Physical lens diameter	mm	Always positive
Refractive Index (n)	Material's refractive index	dimensionless	> 1.0

Lens Types

Click to expand lens type descriptions

• Biconvex: Both surfaces curve outward (R1 > 0, R2 < 0)

  • Use: General magnification, converging light

• Biconcave: Both surfaces curve inward (R1 < 0, R2 > 0)

  • Use: Diverging light, beam expansion

• Plano-Convex: One flat, one convex surface (R1 or R2 = ∞)

  • Use: Focusing, collimation

• Plano-Concave: One flat, one concave surface

  • Use: Light divergence, beam expansion

• Meniscus Convex: Crescent shape, thicker at center

  • Use: Correcting aberrations

• Meniscus Concave: Crescent shape, thinner at center

  • Use: Special optical applications

Common Optical Materials

Material	Refractive Index (n)	Typical Uses
BK7 (Borosilicate Crown Glass)	1.5168	General purpose optics
Fused Silica	1.4585	UV applications, high precision
Crown Glass	1.52	Low-cost optics
Flint Glass	1.6 - 1.7	High refractive power
SF11 (Dense Flint)	1.78	Compact optical systems
Sapphire	1.77	Durable, scratch-resistant

---

The Lensmaker's Equation

openlens uses the thick lens lensmaker's equation to calculate focal length:

1/f = (n-1) * [1/R1 - 1/R2 + (n-1)*d/(n*R1*R2)]

Where:

• f = focal length (mm)
• n = refractive index of the lens material
• R1 = radius of curvature of the front surface (mm)
• R2 = radius of curvature of the back surface (mm)
• d = center thickness (mm)

Sign Convention:

• Positive radius → surface curves toward object (convex)
• Negative radius → surface curves away from object (concave)
• Positive focal length → converging lens
• Negative focal length → diverging lens

Optical Power:

P = 1/f  (in mm⁻¹)
P = 1000/f  (in diopters, D)

---

Data Storage

Database Format

Lenses and optical systems are stored in openlens.db using SQLite for robust, relational data management. This ensures data integrity and supports complex relationships between lenses and assemblies.

Exporting and Sharing

While the main database is SQLite, you can still export individual lenses to JSON format for sharing via the Export tab in the application.

To backup your entire lens library, simply copy the database file:

cp openlens.db openlens_backup_$(date +%Y%m%d).db

---

Testing

openlens includes comprehensive functional tests to ensure accuracy and reliability.

Run All Tests

python3 -m unittest discover -s tests -t .

# Skip slow/integration suites for a quick pass
OPENLENS_SKIP_SLOW=1 python3 -m unittest discover -s tests -t .

# Parallel execution (requires pytest + pytest-xdist: pip install -e .[dev])
pytest -n auto tests/

Examples

Example 1: Standard Biconvex Lens

Design a basic converging lens:

• Material: BK7 (n = 1.5168)
• R1: 100 mm (convex)
• R2: -100 mm (convex)
• Thickness: 5 mm
• Diameter: 50 mm

Result: Focal length ≈ 97.6 mm

Example 2: Plano-Convex Lens

Design a simple focusing lens:

• Material: Fused Silica (n = 1.4585)
• R1: 50 mm (convex)
• R2: ∞ (flat) - use a very large value like 10000
• Thickness: 4 mm
• Diameter: 25 mm

Result: Focal length ≈ 109 mm

Example 3: High-Power Lens

Design a strong converging lens:

• Material: SF11 (n = 1.78)
• R1: 30 mm (strongly convex)
• R2: -40 mm (strongly convex)
• Thickness: 8 mm
• Diameter: 20 mm

Result: Short focal length for compact systems

---

Project Structure

openLens/
├── openlens.py              # PySide6 GUI entry point (main window)
├── src/                     # Source package
│   ├── __init__.py
│   ├── lens.py              # Core Lens model
│   ├── optical_system.py    # Multi-element systems
│   ├── lens_editor.py       # CLI application + LensManager
│   ├── ray_tracer.py        # 2D/3D ray tracing engine
│   ├── aberrations.py       # Seidel aberrations
│   ├── optimizer.py         # Lens optimization engine
│   ├── tolerancing.py       # Monte Carlo / sensitivity analysis
│   ├── database.py          # SQLite persistence
│   ├── validation.py        # Input validation
│   ├── services.py          # Service layer
│   ├── constants.py         # Constants and configuration
│   ├── gui/                 # GUI implementation (widgets/, tabs/, dialogs/, theme.py)
│   ├── analysis/            # Spot diagram, PSF/MTF, ghost, wavefront
│   └── io/                  # STEP / ISO 10110 export
├── tests/                   # unittest test suites (~56 files)
├── openlens.db              # Data storage (SQLite, created on first run)
├── requirements.txt         # Runtime dependencies
└── setup.py                 # Package distribution (pip install -e .)

---

Troubleshooting

Issue: "No display name and no $DISPLAY environment variable" / Qt platform plugin errors

This occurs when running on a headless server or via SSH without X11 forwarding.

Solutions:

• If using SSH: Connect with X11 forwarding: ssh -X user@host
• If running locally: Ensure your display server is running (restart your desktop environment if needed)
• For remote headless servers: Use a virtual display:

  sudo apt-get install xvfb
  xvfb-run python3 openlens.py

  or force Qt's offscreen platform for testing:

  QT_QPA_PLATFORM=offscreen python3 openlens.py

• WSL users: Install an X server like VcXsrv or X410, then:

  export DISPLAY=:0
  python3 openlens.py

Issue: PySide6 not found

Error: ModuleNotFoundError: No module named 'PySide6'

Solution:

pip install PySide6
# or
pip install -r requirements.txt

Issue: Lenses not saving

Solution:

• Check write permissions in the directory
• Ensure openlens.db is not locked by another process
• Check disk space

Issue: 3D visualization not working

Solution:

# Install required dependencies
pip install matplotlib numpy

# Or if using venv:
source venv/bin/activate
pip install matplotlib numpy

---

Contributing

Contributions are welcome! We appreciate bug fixes, new features, documentation improvements, and more.

How to Contribute

Please read our comprehensive Contributing Guidelines for:

• Code of conduct
• Development setup
• Coding standards
• Testing requirements
• Pull request process
• Issue guidelines

Quick Start for Contributors

# 1. Fork the repository
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/openLens.git
cd openLens

# 3. Create a branch
git checkout -b feature/my-feature

# 4. Make changes and test
python3 -m unittest discover -s tests -t .

# 5. Submit a pull request

See CONTRIBUTING.md for detailed instructions.

---

License

This project is open source and available under the MIT License.

---

Contact & Support

For questions, issues, or suggestions:

• Bug reports: Create an issue with the bug label
• Feature requests: Create an issue with the enhancement label
• Questions: Open a discussion or issue with the question label
• Security issues: Contact maintainers directly (see repository)

---

Happy Lens Designing! 🔬

openlens - Making optical design accessible