| Name | zospy JSON |
| Version |
1.2.1
JSON |
| download |
| home_page | |
| Summary | A Python package used to communicate with Zemax OpticStudio through the API |
| upload_time | 2024-03-11 15:37:45 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9,<3.13 |
| license | |
| keywords |
zemax
opticstudio
api
zosapi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ZOSPy
[](https://pypi.org/project/zospy)
[](https://anaconda.org/conda-forge/zospy)
[](https://zospy.readthedocs.io/en/latest/?badge=latest)
## About
Wrapper around the [Ansys Zemax OpticStudio](https://www.zemax.com/pages/opticstudio) API that provides a more pythonic and
intuitive way to interact with the [ZOS-API](https://www.zemax.com/blogs/free-tutorials/getting-started-with-zos-api)
through python using a .NET connection. It thereby allows you to do more
optics modelling with less coding.
In addition to full access to all the OpticStudio fucntions through the ZOS-API, ZOSPy provides the following features:
- Wrapper functions for several OpticStudio analyses in `zospy.analyses`;
- Easy access to solvers in `zospy.solvers`;
- Easy access to all API constants in `zospy.constants`;
- Autocomplete for all ZOS-API endpoints and constants;
- Solves common problems related to Python.NET 3 and interaction with the ZOS-API.
## Waranty and liability
The code is provided as is, without any warranty. It is solely intended for research purposes. No warranty is given and
no rights can be derived from it, as is also stated in the [MIT license](LICENSE.txt).
## Installing
ZOSPy is available on PyPi
```
pip install zospy
```
And through conda:
```
conda install conda-forge::zospy
```
## Dependencies
ZOSPy officially supports Python 3.9 - 3.12. It may work with older Python versions, but support is not provided for
these versions.
### Python packages
- [Python for .NET](http://pythonnet.github.io/) 3.0.3
- [pandas](https://pandas.pydata.org/)
- [NumPy](https://numpy.org/)
- [SemVer](https://python-semver.readthedocs.io/en/latest/index.html) 3.0.2
### Software
- [Ansys Zemax OpticStudio](https://www.zemax.com/pages/opticstudio)
### Compatibility
ZOSPy is tested with the following versions of Python and Ansys Zemax OpticStudio:
| Zemax | 20.3.2 | 23.1.0 | 23.2.1 | 24.1.0 |
|-------------|--------|--------|--------|--------|
| Python 3.9 | ⚠ | ✔ | ✔ | ✔ |
| Python 3.10 | ⚠ | ✔ | ✔ | ✔ |
| Python 3.11 | ⚠ | ✔ | ✔ | ✔ |
| Python 3.12 | ⚠ | | | ✔ |
✔: This version works without problems.
⚠: This version works, but the output of analyses can differ slightly from the used reference version (currently **OpticStudio 23 R1.01**).
## Referencing
When publishing results obtained with this package, please cite the paper in which the package was first used:<br>
van Vught L, Que I, Luyten GPM and Beenakker JWM.
_Effect of anatomical differences and intraocular lens design on Negative Dysphotopsia._
JCRS: Sep 06, 2022.
[doi: [10.1097/j.jcrs.0000000000001054](https://doi.org/10.1097/j.jcrs.0000000000001054) ] [[JCRS](https://journals.lww.com/jcrs/Abstract/9900/Effect_of_anatomical_differences_and_intraocular.107.aspx)]
If a direct reference of the package is also required, reference it using the following DOI:<br>
[](https://zenodo.org/badge/latestdoi/403590410)
## Contributing
Please read our [contribution guidelines](CONTRIBUTING.md) prior to opening a Pull Request.
## Basic usage
### Initiating connection
The connection as extension to running software OpticStudio is initiated as:
```python
import zospy as zp
zos = zp.ZOS()
oss = zos.connect("extension")
```
Make sure that the OpticStudio software is set up to be connected to as extension through the API. Alternatively, a
standalone OpticStudio application can be launched by changing the last line to:
```python
oss = zos.connect("standalone")
```
### Using solvers
Solvers for the Lens Data Editor are available through `zp.solvers`. Every solver requires a surface as its first
parameter.
#### Examples
```python
import zospy.solvers as solvers
surface = oss.LDE.GetSurfaceAt(2)
solvers.position(surface.ThicknessCell, from_surface=1, length=10)
```
### Performing analyses
Implemented analyses are available though `zp.analyses`. The available analyses are grouped in files that correspond to
the analysis groups in OpticStudio (e.g. `zp.analyses.mtf`and `zp.analyses.wavefront`). Every analysis requires the
OpticStudioSystem `oss` as first parameter.
#### Examples
```python
from zp.analyses.mtf import fft_through_focus_mtf
mtf = fft_through_focus_mtf(oss, sampling='64x64', deltafocus=0.1, oncomplete='Close')
```
```python
from zp.analyses.reports import cardinal_points
cp = cardinal_points(oss, surf1=3, surf2=4, oncomplete='Release')
```
A full description of the available function parameters is provided in the docstrings.
### Constants
After initiating the connection, all api constants are available through `zp.constants` (
e.g. `zp.constants.Editors.LDE.SurfaceType`). Note that these are only available after `zos.wakeup()` has been called,
as explained under **Initiating connection**.
### Convenience functions
Some convenience functions are available through `zp.functions`, e.g. to change a surface to a standard stuface:
```python
newsurf = oss.LDE.InsertNewSurfaceAt(0)
zp.functions.lde.surface_change_type(newsurf, 'Standard')
```
### Full example
This example creates a simple optical system consisting of a single lens.
```python
# Create a new, empty system
oss.new()
# Set aperture and wavelength
oss.SystemData.Aperture.ApertureType = zp.constants.SystemData.ZemaxApertureType.FloatByStopSize
oss.SystemData.Wavelengths.GetWavelength(1).Wavelength = 0.543 # in μm
# Set the object at infinity
surface_object = oss.LDE.GetSurfaceAt(0)
surface_object.Thickness = float("inf")
# Use a very small stop size, so the system is approximately paraxial
surface_stop = oss.LDE.GetSurfaceAt(1)
surface_stop.SemiDiameter = 0.1
# Add a lens with n = 1.5
lens_front = oss.LDE.InsertNewSurfaceAt(2)
lens_front.Comment = "lens front"
lens_front.Radius = 20
lens_front.Thickness = 1
zp.solvers.material_model(lens_front.MaterialCell, refractive_index=1.5)
lens_back = oss.LDE.InsertNewSurfaceAt(3)
lens_back.Comment = "lens back"
lens_back.Radius = -20
lens_back.Thickness = 19.792 # System is in focus
```
### Logging
Some basic logging is implemented through the
standard [python logging module](https://docs.python.org/3/library/logging.html) (but still under development). The
following implementation examples assume that `import logging` has been executed.
1. To enable logging output from all ZOSPy and other modules using logging.basicConfig:
```python
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
```
2. To enable logging output from all ZOSPy and other modules using a root logger:
```python
fmt = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
sh = logging.StreamHandler()
sh.setFormatter(fmt)
sh.setLevel(logging.DEBUG)
logger = logging.getLogger()
logger.addHandler(sh)
```
3. To enable logging output from only ZOSPy
```python
logging.getLogger('zospy').addHandler(logging.StreamHandler())
logging.getLogger('zospy').setLevel(logging.INFO)
```
## Contact
Feel free to contact us for any inquiries:
- C. Haasjes ([email](mailto:c.haasjes@lumc.nl))
- J.W.M. Beenakker ([email](mailto:j.w.m.beenakker@lumc.nl))
- L. van Vught ([email](mailto:l.van_vught@lumc.nl))
Raw data
{
"_id": null,
"home_page": "",
"name": "zospy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<3.13",
"maintainer_email": "",
"keywords": "Zemax,OpticStudio,API,ZOSAPI",
"author": "",
"author_email": "Luc van Vught <l.van_vught@lumc.nl>, Jan-Willem Beenakker <j.w.m.beenakker@lumc.nl>, Corn\u00e9 Haasjes <c.haasjes@lumc.nl>",
"download_url": "https://files.pythonhosted.org/packages/f0/93/84655c26bca86724e303e48a57032d55c8dcb1b95b6bb8717afd6a01304c/zospy-1.2.1.tar.gz",
"platform": null,
"description": "# ZOSPy\n\n[](https://pypi.org/project/zospy)\n\n[](https://anaconda.org/conda-forge/zospy)\n\n[](https://zospy.readthedocs.io/en/latest/?badge=latest)\n\n## About\n\nWrapper around the [Ansys Zemax OpticStudio](https://www.zemax.com/pages/opticstudio) API that provides a more pythonic and\nintuitive way to interact with the [ZOS-API](https://www.zemax.com/blogs/free-tutorials/getting-started-with-zos-api)\nthrough python using a .NET connection. It thereby allows you to do more\noptics modelling with less coding.\n\nIn addition to full access to all the OpticStudio fucntions through the ZOS-API, ZOSPy provides the following features:\n\n- Wrapper functions for several OpticStudio analyses in `zospy.analyses`;\n- Easy access to solvers in `zospy.solvers`;\n- Easy access to all API constants in `zospy.constants`;\n- Autocomplete for all ZOS-API endpoints and constants;\n- Solves common problems related to Python.NET 3 and interaction with the ZOS-API. \n\n## Waranty and liability\n\nThe code is provided as is, without any warranty. It is solely intended for research purposes. No warranty is given and\nno rights can be derived from it, as is also stated in the [MIT license](LICENSE.txt).\n\n## Installing\n\nZOSPy is available on PyPi\n\n```\npip install zospy\n```\n\nAnd through conda:\n\n```\nconda install conda-forge::zospy\n```\n\n## Dependencies\n\nZOSPy officially supports Python 3.9 - 3.12. It may work with older Python versions, but support is not provided for\nthese versions.\n\n### Python packages\n\n- [Python for .NET](http://pythonnet.github.io/) 3.0.3\n- [pandas](https://pandas.pydata.org/)\n- [NumPy](https://numpy.org/)\n- [SemVer](https://python-semver.readthedocs.io/en/latest/index.html) 3.0.2\n\n### Software\n\n- [Ansys Zemax OpticStudio](https://www.zemax.com/pages/opticstudio)\n\n### Compatibility\n\nZOSPy is tested with the following versions of Python and Ansys Zemax OpticStudio:\n\n| Zemax | 20.3.2 | 23.1.0 | 23.2.1 | 24.1.0 |\n|-------------|--------|--------|--------|--------|\n| Python 3.9 | \u26a0 | \u2714 | \u2714 | \u2714 |\n| Python 3.10 | \u26a0 | \u2714 | \u2714 | \u2714 |\n| Python 3.11 | \u26a0 | \u2714 | \u2714 | \u2714 |\n| Python 3.12 | \u26a0 | | | \u2714 |\n\n\u2714: This version works without problems.\n\u26a0: This version works, but the output of analyses can differ slightly from the used reference version (currently **OpticStudio 23 R1.01**).\n\n## Referencing\n\nWhen publishing results obtained with this package, please cite the paper in which the package was first used:<br>\nvan Vught L, Que I, Luyten GPM and Beenakker JWM.\n_Effect of anatomical differences and intraocular lens design on Negative Dysphotopsia._\nJCRS: Sep 06, 2022.\n[doi: [10.1097/j.jcrs.0000000000001054](https://doi.org/10.1097/j.jcrs.0000000000001054) ] [[JCRS](https://journals.lww.com/jcrs/Abstract/9900/Effect_of_anatomical_differences_and_intraocular.107.aspx)]\n\nIf a direct reference of the package is also required, reference it using the following DOI:<br>\n[](https://zenodo.org/badge/latestdoi/403590410)\n\n## Contributing\n\nPlease read our [contribution guidelines](CONTRIBUTING.md) prior to opening a Pull Request.\n\n## Basic usage\n\n### Initiating connection\n\nThe connection as extension to running software OpticStudio is initiated as:\n\n```python\nimport zospy as zp\n\nzos = zp.ZOS()\noss = zos.connect(\"extension\")\n```\n\nMake sure that the OpticStudio software is set up to be connected to as extension through the API. Alternatively, a\nstandalone OpticStudio application can be launched by changing the last line to:\n\n```python\noss = zos.connect(\"standalone\")\n```\n\n### Using solvers\n\nSolvers for the Lens Data Editor are available through `zp.solvers`. Every solver requires a surface as its first\nparameter.\n\n#### Examples\n\n```python\nimport zospy.solvers as solvers\n\nsurface = oss.LDE.GetSurfaceAt(2)\nsolvers.position(surface.ThicknessCell, from_surface=1, length=10)\n```\n\n### Performing analyses\n\nImplemented analyses are available though `zp.analyses`. The available analyses are grouped in files that correspond to\nthe analysis groups in OpticStudio (e.g. `zp.analyses.mtf`and `zp.analyses.wavefront`). Every analysis requires the\nOpticStudioSystem `oss` as first parameter.\n\n#### Examples\n\n```python\nfrom zp.analyses.mtf import fft_through_focus_mtf\n\nmtf = fft_through_focus_mtf(oss, sampling='64x64', deltafocus=0.1, oncomplete='Close')\n```\n\n```python\nfrom zp.analyses.reports import cardinal_points\n\ncp = cardinal_points(oss, surf1=3, surf2=4, oncomplete='Release')\n```\n\nA full description of the available function parameters is provided in the docstrings.\n\n### Constants\n\nAfter initiating the connection, all api constants are available through `zp.constants` (\ne.g. `zp.constants.Editors.LDE.SurfaceType`). Note that these are only available after `zos.wakeup()` has been called,\nas explained under **Initiating connection**.\n\n### Convenience functions\n\nSome convenience functions are available through `zp.functions`, e.g. to change a surface to a standard stuface:\n\n```python\nnewsurf = oss.LDE.InsertNewSurfaceAt(0)\nzp.functions.lde.surface_change_type(newsurf, 'Standard')\n```\n\n### Full example\n\nThis example creates a simple optical system consisting of a single lens.\n\n```python\n# Create a new, empty system\noss.new()\n\n# Set aperture and wavelength\noss.SystemData.Aperture.ApertureType = zp.constants.SystemData.ZemaxApertureType.FloatByStopSize\noss.SystemData.Wavelengths.GetWavelength(1).Wavelength = 0.543 # in \u03bcm\n\n# Set the object at infinity\nsurface_object = oss.LDE.GetSurfaceAt(0)\nsurface_object.Thickness = float(\"inf\")\n\n# Use a very small stop size, so the system is approximately paraxial\nsurface_stop = oss.LDE.GetSurfaceAt(1)\nsurface_stop.SemiDiameter = 0.1\n\n# Add a lens with n = 1.5\nlens_front = oss.LDE.InsertNewSurfaceAt(2)\nlens_front.Comment = \"lens front\"\nlens_front.Radius = 20\nlens_front.Thickness = 1\nzp.solvers.material_model(lens_front.MaterialCell, refractive_index=1.5)\n\nlens_back = oss.LDE.InsertNewSurfaceAt(3)\nlens_back.Comment = \"lens back\"\nlens_back.Radius = -20\nlens_back.Thickness = 19.792 # System is in focus\n```\n\n### Logging\n\nSome basic logging is implemented through the\nstandard [python logging module](https://docs.python.org/3/library/logging.html) (but still under development). The\nfollowing implementation examples assume that `import logging` has been executed.\n\n1. To enable logging output from all ZOSPy and other modules using logging.basicConfig:\n ```python\n logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n ```\n2. To enable logging output from all ZOSPy and other modules using a root logger:\n ```python\n fmt = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\n sh = logging.StreamHandler()\n sh.setFormatter(fmt)\n sh.setLevel(logging.DEBUG)\n\n logger = logging.getLogger()\n logger.addHandler(sh)\n ```\n3. To enable logging output from only ZOSPy\n ```python\n logging.getLogger('zospy').addHandler(logging.StreamHandler())\n logging.getLogger('zospy').setLevel(logging.INFO)\n ```\n\n## Contact\n\nFeel free to contact us for any inquiries:\n\n- C. Haasjes ([email](mailto:c.haasjes@lumc.nl))\n- J.W.M. Beenakker ([email](mailto:j.w.m.beenakker@lumc.nl))\n- L. van Vught ([email](mailto:l.van_vught@lumc.nl))\n",
"bugtrack_url": null,
"license": "",
"summary": "A Python package used to communicate with Zemax OpticStudio through the API",
"version": "1.2.1",
"project_urls": {
"Documentation": "https://mreye-lumc.github.io/ZOSPy",
"Source": "https://github.com/MREYE-LUMC/ZOSPy"
},
"split_keywords": [
"zemax",
"opticstudio",
"api",
"zosapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fbff1dd2495936ea0b8b28d48f93d4fbbb99b3c9016a17e1cb034774ecd2d200",
"md5": "31469c7b6eb34af8d6b51ee3baa5afb6",
"sha256": "f26535ea2873fe811edc18c7280a5960a5e49e8d2505b468f2061f1fec030a26"
},
"downloads": -1,
"filename": "zospy-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31469c7b6eb34af8d6b51ee3baa5afb6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<3.13",
"size": 222543,
"upload_time": "2024-03-11T15:37:43",
"upload_time_iso_8601": "2024-03-11T15:37:43.588674Z",
"url": "https://files.pythonhosted.org/packages/fb/ff/1dd2495936ea0b8b28d48f93d4fbbb99b3c9016a17e1cb034774ecd2d200/zospy-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f09384655c26bca86724e303e48a57032d55c8dcb1b95b6bb8717afd6a01304c",
"md5": "5b8cc8690f44efe1f45c1f3063a8e170",
"sha256": "9dec1f835d3150162ced9cc67f6612f253fb4d3ada1a611c6ad3d24dfd978986"
},
"downloads": -1,
"filename": "zospy-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "5b8cc8690f44efe1f45c1f3063a8e170",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<3.13",
"size": 174383,
"upload_time": "2024-03-11T15:37:45",
"upload_time_iso_8601": "2024-03-11T15:37:45.679982Z",
"url": "https://files.pythonhosted.org/packages/f0/93/84655c26bca86724e303e48a57032d55c8dcb1b95b6bb8717afd6a01304c/zospy-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-11 15:37:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MREYE-LUMC",
"github_project": "ZOSPy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "zospy"
}
