{"id":13597983,"url":"https://github.com/ricktu288/ray-optics","last_synced_at":"2025-05-14T11:09:51.325Z","repository":{"id":41380795,"uuid":"52271379","full_name":"ricktu288/ray-optics","owner":"ricktu288","description":"A web app for creating and simulating 2D geometric optical scenes, with a gallery of (interactive) demos.","archived":false,"fork":false,"pushed_at":"2025-05-04T20:31:16.000Z","size":163873,"stargazers_count":1455,"open_issues_count":13,"forks_count":234,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-05-04T21:20:24.257Z","etag":null,"topics":["canvas","geometric-optics","html5","optics","optics-simulation","ray-optics"],"latest_commit_sha":null,"homepage":"https://phydemo.app/ray-optics/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ricktu288.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-02-22T12:18:34.000Z","updated_at":"2025-05-04T20:06:00.000Z","dependencies_parsed_at":"2023-10-15T19:30:37.953Z","dependency_job_id":"4beea9a8-ce7a-4ebe-80f5-7aefe4fd00f6","html_url":"https://github.com/ricktu288/ray-optics","commit_stats":{"total_commits":1282,"total_committers":27,"mean_commits":47.48148148148148,"dds":0.2948517940717629,"last_synced_commit":"7af7a977a869368f7d82b408fe801f8e03668320"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricktu288%2Fray-optics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricktu288%2Fray-optics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricktu288%2Fray-optics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricktu288%2Fray-optics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ricktu288","download_url":"https://codeload.github.com/ricktu288/ray-optics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129489,"owners_count":22019628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["canvas","geometric-optics","html5","optics","optics-simulation","ray-optics"],"created_at":"2024-08-01T17:00:45.038Z","updated_at":"2025-05-14T11:09:51.317Z","avatar_url":"https://github.com/ricktu288.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"![Example figure](https://raw.githubusercontent.com/ricktu288/ray-optics/master/src/img/spherical-lens-and-mirror.jpg)\n\n# Ray Optics Simulation\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6386611.svg)](https://doi.org/10.5281/zenodo.6386611)\n[![translated](https://hosted.weblate.org/widget/ray-optics-simulation/svg-badge.svg)](https://hosted.weblate.org/engage/ray-optics-simulation/)\n[![Deploy website](https://github.com/ricktu288/ray-optics/actions/workflows/deploy.yml/badge.svg)](https://github.com/ricktu288/ray-optics/actions/workflows/deploy.yml)\n[![Deploy integrations](https://github.com/ricktu288/ray-optics/actions/workflows/deploy-integrations.yml/badge.svg)](https://github.com/ricktu288/ray-optics/actions/workflows/deploy-integrations.yml)\n\nA web app for creating and simulating 2D geometric optical scenes, with a gallery of (interactive) demos.\n\n## Features\n- Simulate various light sources: ray, parallel/divergent beam, and point source\n- Simulate reflection in linear or curved mirrors, which can be defined by a custom equation\n- Simulate beam splitters and dichroic mirrors\n- Simulate refraction in linear or curved interfaces, which can be defined by a custom equation\n- Simulate ideal lens/mirror, which obey the lens/mirror equation\n- Simulate spherical lens defined by front/back focal distances\n- Simulate gradient-index material defined by a custom refractive index function\n- Simulate mixture of colors, color filtering, and chromatic dispersion\n- Simulate diffraction gratings.\n- View extensions of rays to see if they converge to a virtual image\n- View real images, virtual images, and virtual objects directly\n- View images that can be observed from some given position\n- Distance, angular, energy flow, and momentum flow measurements\n- Draw irradiance map and export as CSV data\n- Export as SVG diagram\n- Create modularized combinations of optical elements with custom parameters.\n- Use the simulator as a node module in your own project and integrate with other programming languages.\n\n## Links\n- [**Launch the Web App**](https://phydemo.app/ray-optics/simulator/)\n- [Gallery](https://phydemo.app/ray-optics/gallery/)\n- [Documentation](https://phydemo.app/ray-optics/docs/index.html)\n- [About](https://phydemo.app/ray-optics/about)\n- [Run Locally](https://github.com/ricktu288/ray-optics/blob/master/run-locally/README.md)\n\n## Cite this project\n\nIf you use this project in your research, please cite it according to the metadata:\n```bibtex\n@misc{RayOptics,\n  author = {Tu, Yi-Ting and others},\n  title = {{Ray Optics Simulation}},\n  year = {2016},\n  doi = {10.5281/zenodo.6386611},\n  url = {https://phydemo.app/ray-optics/}\n}\n```\n\nThe DOI shown above is for the project, not for a specific version. If you want to cite a versioned DOI, please use the [latest release](https://github.com/ricktu288/ray-optics/releases/latest), which is slightly older than the online version and without beta features. You can then replace the project DOI above with the versioned DOI shown on that page, and the year by the year of the release.\n\nThe URL field above is optional and not supported by all citation formats. You may also use the Zenodo URL or the GitHub URL.\n\n## Contributing\n\nContributions are welcome. For the following types of contributions, no (or little) programming knowledge is required:\n\n- New items in the [gallery](https://phydemo.app/ray-optics/gallery/)\n- New translations\n- New modules (as in Tools -\u003e Other -\u003e Import Modules)\n\nSee [CONTRIBUTING.md](https://github.com/ricktu288/ray-optics/blob/master/CONTRIBUTING.md) for the tutorial.\n\nFor translations, note that this project uses Weblate. Please visit https://hosted.weblate.org/engage/ray-optics-simulation/ to translate.\n\n[![Translation status](https://hosted.weblate.org/widget/ray-optics-simulation/287x66-grey.png)](https://hosted.weblate.org/engage/ray-optics-simulation/)\n\nTo contribute code, you need to have some knowledge of JavaScript and module bundling. The code is written in ES6 and bundled with Webpack. The code structure is documented in the [documentation](https://phydemo.app/ray-optics/docs/index.html). See the following section for installation instructions.\n\n## Installation\n\n\u003e [!NOTE]\n\u003e The following instructions are for developers. If you just want to use the web app, you can launch it directly from [here](https://phydemo.app/ray-optics/simulator/).\n\u003e If you just want to run the project locally, please see [Run Locally](https://github.com/ricktu288/ray-optics/blob/master/run-locally/README.md).\n\nTo run the web app locally for development, you need to have Node.js installed. Then, run the following commands in the terminal:\n```bash\ngit clone https://github.com/ricktu288/ray-optics.git\ncd ray-optics\nnpm install --no-optional\nnpm run start\n```\nAfter that, the simulator web app should be running at `http://localhost:8080/simulator/`. Note however that some links and the \"import module\" window will not work because the other part of the project is not built.\n\nIf you want to build the entire project, including the home pages, gallery, modules, documentation, and the node version of the simulator, you can run the following command:\n```bash\nnpm install\nnpm run build\n```\nAfter that, the entire content for the [https://phydemo.app/ray-optics/](https://phydemo.app/ray-optics/) website will be in the `dist` folder. You can again run `npm run start` to run the simulator locally, and now all the links and the \"import module\" window should work.\n\nIf an error occurs during the installation, some common reasons are:\n- The version of Node.js is too old. You can update Node.js to version 18 or later.\n- Some system dependencies for node-canvas are missing. You can find the instructions for installing the dependencies in the [node-canvas repository](https://github.com/Automattic/node-canvas).\n\nThe full build may takes about half an hour to complete due to the generation of the large numbers of images for the gallery.\n\n## Project structure\n\n- `src` contains the source code for the project.\n- `data` contains the data for gallery, modules, and the list of contributors.\n- `locales` contains the translations for the project in i18next format, managed by Weblate.\n- `scripts` contains the scripts for custom build steps.\n- `test` contains the automatic tests for the project.\n- `integrations` contains the integration tools for the simulator with other programming languages.\n- `dist` (generated at build time) contains the built files for the project (the entire content for the [https://phydemo.app/ray-optics](https://phydemo.app/ray-optics) website).\n- `dist-node` (generated at build time) contains the built files for the node module version of the simulator, which is required for the image generation, and can also be used in your own project.\n- `dist-integrations` (generated at build time) contains the built files for the integration tools.\n\nSee the README.md in each directory for more information.\n\n## Development\n\nFor development of the web app, you can just use `npm run start`, and the web app will be automatically reloaded when some code for the simulator is modified. However, to rebuild some other part of this project, you need to run the following commands:\n```bash\n# build home pages, about pages, gallery, and modules pages (not including scenes and image generation).\nnpm run build-pages\n\n# build the scenes for the gallery and modules pages.\nnpm run build-scenes\n\n# build the node module version of the simulator, which is required for the image generation.\nnpm run build-node\n\n# generate images for the gallery, which may take a long time.\nnpm run build-images\n\n# build the web app version of simulator (unlike npm run start, this command builds the simulator in production mode)\nnpm run build-app\n\n# build documentation\nnpm run build-docs\n```\nNote that `npm run build` is equivalent to running all the above commands.\n\n## Testing\n\nTo run the automatic tests,\n```bash\nnpm run test\n```\nThe tests are run automatically when you commit your changes.\n\nThe above command will run the following tests:\n```bash\nnpm run test:sceneObjs\nnpm run test:scenes\n```\nthe first one tests the user creation, dragging, and changing properties for each scene object in the source code.\nthe second one runs the scene JSONs in `test/scenes/` with the node module version of the simulator, and compares the output of `CropBox`/`Detector` with the corresponding PNG/CSV files.\n\nIf you modify the appearance of some objects or rays, the images in `test/scenes/` may need to be updated. Also if you add new scene tests, the corresponding PNG and CSV files nees to be initialized. In these cases, run the following command to regenerate all the PNG/CSV files after you make sure that all the failing tests are due to the changes you made:\n```bash\nenv WRITE_OUTPUT=true npm run test:scenes\n```\nPlease do not run this command if you are not sure that all the failing tests are due to the changes you made, since after running it, all scene tests will pass vacuously.\n\nCurrently there is no automatic end-to-end test for the web app. So please manually check that the UI works as expected if you make any changes.\n\n## Use as a Node Module\n\nThe simulator can be used as a node module in your own project and integrated with other programming languages.\nThe easiest way is to use the built [integration tools](https://github.com/ricktu288/ray-optics/tree/dist-integrations). You don't need to clone this repo and build anything, but you still need to have Node.js installed.\n\nFor more advanced usage, the node module version of the simulator is built with the following command:\n```bash\nnpm run build-node\n```\nAfter that, you can use the simulator in your own project by importing the module:\n```javascript\nconst { Scene, Simulator, sceneObjs, geometry } = require('path/to/ray-optics/dist-node/rayOptics.js');\n```\n\nSee the [documentation](https://phydemo.app/ray-optics/docs/index.html) for more information about the API. For a usage example, see the [image generation script](https://github.com/ricktu288/ray-optics/blob/master/scripts/buildImages.mjs).\n\nTo build the integration tools by yourself, run the following command:\n```bash\nnpm run build-integrations\n```\n\n## License\n\n```\nCopyright 2016–2025 The Ray Optics Simulation authors and contributors\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricktu288%2Fray-optics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fricktu288%2Fray-optics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricktu288%2Fray-optics/lists"}