Skip to content

Latest commit

 

History

History
145 lines (108 loc) · 5.93 KB

installation_and_usage.md

File metadata and controls

145 lines (108 loc) · 5.93 KB

Installation

Start by installing the necessary tools and launching the Viewer, then experiment with modifying the existing projects, and finally create your own projects. TPVector projects are written in TypeScript.

  • It's easiest to obtain the necessary development tools using Docker. Install Docker (note that Docker on Windows requires WSL).

    Without Docker

    You can also use TPVector without Docker, however you need to be on linux or WSL, and install the tools manually. You can treat the dockerfile as an instruction for configuring the environment. Then launch the commands from the cmds directory manually (normally Docker runs cmds/viewer by default).

  • The recommended IDE is Visual Studio Code, with the following extensions:

    You can however use a different IDE (or no IDE) as well.

  • Clone or fork the TPVector git repository on your machine. For this you need a git client, for example GitHub Desktop or git.

Usage

Viewer

The Viewer is a part of the TPVector library. It is a web application that generates the SVG files, shows them for preview and saves them for usage in the laser cutter software.

Starting the Viewer

In Visual Studio Code

Run the Run/Debug configuration Viewer (Docker). This will build and start a Docker container which serves the Viewer app, and open the app in the browser (at http://localhost:4327/).

Without Docker

You can use the Viewer (local) configuration instead to run Viewer using the locally installed development tools.

Without Visual Studio Code

  • Build and start the Docker container defined in docker-compose.yml. This can be done in multiple ways:

    • from the Docker Desktop, or
    • from the command line: docker compose -f docker/docker-compose.yml up.

    Without Docker

    Run directly cmds/viewer to start the Viewer.

  • Open the Viewer in the browser, at http://localhost:4327/.

More details

The TypeScript code of the library and the projects is bundled together and served to the browser. All the logic of generating the SVGs ( both for preview and for the laser software) is executed in the browser.

The bundler used to serve the Viewer is esbuild, launched by cmds/viewer, which happens automatically if you start the Docker container as described above.

The Viewer initially shows the demo projects, defined in demos. See below for how to add your own projects.

Where to start in the code

Take a look at the code entry point, which is src/viewer/viewer.ts, browse the demo projects, try making changes. Changes in the code are immediately caught by the Viewer, and the browser is refreshed to show the result.

Note: The Viewer process does not perform type-checking. For TypeScript type-checking you need to either rely on your IDE, or run the checker manually, using cmds/type-check, or the Type-check task in VS Code.

Custom projects

There are two main ways to start developing your own projects:

Directly in the TPVector repository (easiest)

  • In your fork of the TPVector repository, create a new branch for your project(s).
  • Pick a directory for your projects under src. You can put your files directly in src/demos along with the demo files, or you can create another directory, like src/my_projects.
  • Add your projects to src/viewer/viewer.ts.
  • Start the Viewer. Your projects will be shown along with the demo projects.

In a separate repository

  • Pick a directory for your projects under src. If you want it to be git-ignored, pick src/proj, otherwise pick a different name (whether you want it to be git-ignored or not might depend on your workflow, e.g. in VS Code a sub-repository works better if it's not git-ignored). Let's say you pick my_projects.
  • Init your projects' repository in the selected directory (now or later).
  • Run cmds/set-up-custom-projects-dir my_projects (see cmds/set-up-custom-projects-dir). This will do the following:
    • Create src/my_projects directory (unless exists).
    • Create src/my_projects/viewer.ts file (unless exists) as a copy of src/viewer/viewer.ts.
    • Create src/my_projects/projects-viewer shell script (unless exists) which runs the Viewer with the previously created copy of viewer.ts as the entry point.
    • Create cmds/projects-viewer shell script calling the previously created projects-viewer. This will cause the cmds/viewer to run this file instead of cmds/demos-viewer.
  • If the Docker container is running, stop it, as it will need to be recreated after the change of the script.
  • Add your projects to src/my_projects/viewer.ts.
  • Start the Viewer. Your projects will be shown along with the demo projects (unless you delete them from src/my_projects/viewer.ts).

You can make any necessary changes to the src/my_projects/projects-viewer script, e.g. add more loaders.