CubeSat Lens Designer (Optiland)

This toolkit helps you design a 150mm f/1.5 lens for a CubeSat payload using professional-grade optical optimization (Optiland). The tool automatically designs the lens and displays it in a 3D GUI.

---

🚦 Quick Start (Recommended)

For Linux users: Use the Local Python method below - it's faster and more reliable than Docker.

For Windows/Mac users: Docker is available but may have display issues. Try it, but local Python is more reliable.

---

💻 Option 1: Local Python (Recommended)

Best for Linux. Faster, no massive downloads, and GUI works reliably.

Step 1: Create Virtual Environment

Open a terminal in the project folder and run:

python3 -m venv venv

Step 2: Install Dependencies

Activate the environment and install all required packages:

source venv/bin/activate
pip install optiland numpy matplotlib torch PySide6 qtconsole

Note: The GUI requires both PySide6 and qtconsole packages. If you get import errors, you likely missed one of these.

Step 3: Run the Tool

Design the lens:

python design_150mm_f15.py

Then launch the GUI:

bash Launch_GUI.sh

Or on Linux, you can double-click:

• design_150mm_f15.py to design the lens
• Launch_GUI.sh to open the GUI viewer

Important: The virtual environment (venv folder) must exist and contain all dependencies. If you delete it, you'll need to repeat Steps 1-2.

---

🐳 Option 2: Docker (Alternative)

Works on Windows, Mac, and Linux without installing Python. But has some issues...

⚠️ Known Issues:

• Requires 14GB download each time (unless cached)
• GUI may not display on Linux (X11 forwarding issues)
• Requires Docker Desktop running constantly
• Slower startup due to image download/extraction

Step 1: Install Docker & Get the Scripts

1. Install Docker Desktop: Download here and ensure it is running.
2. Download the Tool:
   • Click here to download the scripts (ZIP).
   • Unzip the file to your Desktop.
   • Open the folder cubesat_lens-main.

You also need a tool to see the GUI window. Follow the steps for your computer:

🪟 Windows Users:

1. Download and install VcXsrv.
2. Run XLaunch from your Start Menu.
3. Important: When asked for "Extra settings", check the box for "Disable access control".
4. Finish the setup. You must leave this running in the background!

🍎 Mac Users:

1. Download and install XQuartz.
2. Open XQuartz settings -> Security tab.
3. Check "Allow connections from network clients".
4. Restart your Mac (or log out and back in) for this to take effect.

🐧 Linux Users:

You are likely good to go! If you get errors, just run:

sudo apt-get install x11-xserver-utils libxcb-cursor0

Step 2: Run the Design Tool

Open the folder you unzipped (cubesat_lens-main) and choose the "Easy Button" for your computer:

• Windows: Double-click Run_Windows.bat (Note: You need VcXsrv running as described above).

• Mac: Double-click Run_Mac.command (Note: You need XQuartz running as described above).

• Linux:

  1. Open a terminal inside the folder and run:

     ./Run_Docker_Design.sh

  2. Or, run this one-time setup to get a clickable Desktop icon:

     ./Create_Linux_Icon.sh

What happens next?

1. The tool automatically downloads the latest physics engine.
2. It runs the optimization math to design your lens.
3. Once finished, the GUI launches automatically showing your new 3D lens model!

Step 3: Explore

• Click the Design tab to see your 3D lens model.
• Use the menus to analyze performance (Spot Diagrams, Ray Fans, etc.).

---

🛠️ For Maintainers: Publishing Updates

If you modify the source code and want to update the public Docker image:

1. Run the publish script:

   ./publish_image.sh

2. Enter your Docker Hub username and password when prompted.
3. The script will build the new image, push it to Docker Hub, and update Run_Docker_Design.sh to point to the new version.

---

🛠️ For Students: How to Modify the Design

The core logic is in the file design_150mm_f15.py. You can edit this file with any text editor (Notepad, VS Code, etc.).

Key variables to change:

• Change Focal Length: Look for line ~46:

  target_focal_length = 150.0  # Change this to 100.0 or 200.0

• Change Aperture (F-Number): Look for line ~47:

  target_f_number = 1.5        # Change to 2.8 for a slower, easier lens

• Change Glass Types: Look for the lens.add_surface(...) lines. You can swap "N-LAK9" or "SF5" with other standard glass names (e.g., "BK7", "N-SF11").

---

💬 Feedback & Requests

Have a recommendation, comment, or feature request?

Please let us know! We are actively improving this tool for the community.

• Open an issue on GitHub.
• Or leave a comment in our discussion thread.

We review all feedback and are happy to help you get your design working!

---

🔧 Troubleshooting

"Permission Denied" on scripts? Open a terminal in this folder and run:

chmod +x *.sh

GUI won't launch on Linux?

You might be missing a system library for the display. Run this command:

sudo apt-get install libxcb-cursor0

"ModuleNotFoundError: No module named 'PySide6'" or "qtconsole"?

You need to install the GUI dependencies. Make sure you created the virtual environment and installed all packages:

source venv/bin/activate
pip install PySide6 qtconsole

Terminal flashes and disappears when running scripts?

This usually means there's an error but the terminal closes too fast. Run the script from the terminal directly to see the error message:

bash Launch_GUI.sh

Docker GUI won't display on Linux?

The Docker method has known X11 display issues on Linux. We recommend using the Local Python method (Option 1) instead - it's faster and more reliable.