User Tools

Are you interested in helping with the development of Photonic3D? Great! Here is some info that will help you get started.

# Project Architecture

Photonic3D is a modern web application designed with a Java server-side REST API and an HTML/CSS/JS UI. While the server does serve up both the UI pages and the REST API calls, there is no server side processing of the UI pages, all of that content is served as-is directly from the files.

## REST API Server

The server interacts with the UI via REST APIs on the front-end side. Based on calls to the API, it controls the display output, firmware serial communication, and projector serial communication.

The server is implemented in Java, and is a Java SE application that bootstraps a Jetty HTTP server. The API is implemented using the Resteasy implementation of JAX-RS.

We use Swagger for inline API documentation. The API documentation can be accessed from any running Photonic3D server at `http:<server host>:9091/apidoc`
The code for the server is organized to the Maven standard project layout. ## UI The UI is currently implemented using Angular.js and is in the `resourcesnew` directory. Alternative UIs (which do not necessarily need to use Angular.js) can be placed into their own folders. The folder used to serve the UI is selected in ``. The only way for the UI to interact with the server is via the REST API. There is no server-side generation of UI code. We do not use a JSP engine. # Setting Up a Development Environment Start by forking our repository on GitHub. Under most circumstances, you will want to fork our development repo, For immediate fixes for the stable release, you may instead fork the production stable repo To fork a repo, simply visit the repo on GitHub via the above links and click on the “fork” button. Next, you'll need to decide whether you want to set up a development environment on the cloud or on your local PC. A cloud-based development environment is quicker to set up and can be used in a location independent way, although there are conveniences from having a full-fledged local IDE and offline access. ## Cloud 9 IDE - Visit and click the GitHub icon in the upper right to sign in with your GitHub account - Click on Repositories in the left navbar - Locate the forked repo that you created earlier and click Clone to Edit - Set a workspace name (must be all lower case) and select the HTML5 template - Once the repository is populated, open a terminal tab in the bottom pane and execute the following commands: ``` sudo add-apt-repository ppa:webupd8team/java sudo apt-get update sudo apt-get install oracle-java8-set-default ``` There will be some interactive prompts, so you will need to look at the screen and select OK and Yes to the various prompts. When this is finished, Java 8 will be installed in your environment and you'll be able to execute the gradle build commands. The Gradle build script knows when you are in the environment and will change the listen port to match what offers when you click the **Preview* button. Clicking it will take you directly to the Photonic3D UI; you don't need to enter in a URL manually. ## Desktop IDEs # Clone and populate local repo To work locally, you will need to clone a repo to your local computer and initialize submodules. ``` git clone <repo URL> cd <repo directory> git submodule init git submodule update ``` # Building and Running The project uses gradle to build, run, and test the code base. The gradle wrapper is included in the repository, so it is not necessary to install Gradle onto your system. Only a working JDK 8 environment is required. Gradle needs to be run at the command line (both on Windows and Linux). Open a command line prompt and change your working directory to be the `host` directory inside your repository. * `./gradlew assemble` - compile all of the parts of the project * `./gradlew run` - assemble the project, if necessary, and then run Photonic3D on your computer * `./gradlew build` - assemble the project and run unit tests * `./gradlew dist` - assemble the project and create a distribution zip to install onto a Raspberry Pi * `./gradlew fullRelease` - Generates a release to GitHub Releases