diff --git a/docs/assets/Calibration.png b/docs/assets/Calibration.png new file mode 100644 index 00000000..1a5ed4cc Binary files /dev/null and b/docs/assets/Calibration.png differ diff --git a/docs/assets/Camera-efh.png b/docs/assets/Camera-efh.png new file mode 100644 index 00000000..94a752af Binary files /dev/null and b/docs/assets/Camera-efh.png differ diff --git a/docs/assets/CameraSelection.png b/docs/assets/CameraSelection.png new file mode 100644 index 00000000..3848e038 Binary files /dev/null and b/docs/assets/CameraSelection.png differ diff --git a/docs/assets/Creator-efh.png b/docs/assets/Creator-efh.png new file mode 100644 index 00000000..06342e1b Binary files /dev/null and b/docs/assets/Creator-efh.png differ diff --git a/docs/assets/DetectionParameters.png b/docs/assets/DetectionParameters.png new file mode 100644 index 00000000..87bb0b7a Binary files /dev/null and b/docs/assets/DetectionParameters.png differ diff --git a/docs/assets/Display-efh.png b/docs/assets/Display-efh.png new file mode 100644 index 00000000..b3a538cc Binary files /dev/null and b/docs/assets/Display-efh.png differ diff --git a/docs/assets/ai-example.png b/docs/assets/ai-example.png new file mode 100644 index 00000000..4c84017a Binary files /dev/null and b/docs/assets/ai-example.png differ diff --git a/docs/assets/all-interfaces-panel-horizontal.png b/docs/assets/all-interfaces-panel-horizontal.png new file mode 100644 index 00000000..b111f35c Binary files /dev/null and b/docs/assets/all-interfaces-panel-horizontal.png differ diff --git a/docs/assets/all-interfaces-panel.png b/docs/assets/all-interfaces-panel.png new file mode 100644 index 00000000..fc519d8c Binary files /dev/null and b/docs/assets/all-interfaces-panel.png differ diff --git a/docs/assets/configs-efh-horizontal.png b/docs/assets/configs-efh-horizontal.png new file mode 100644 index 00000000..4f44584d Binary files /dev/null and b/docs/assets/configs-efh-horizontal.png differ diff --git a/docs/assets/controller-form.png b/docs/assets/controller-form.png new file mode 100644 index 00000000..c3e62d76 Binary files /dev/null and b/docs/assets/controller-form.png differ diff --git a/docs/assets/model-form.png b/docs/assets/model-form.png new file mode 100644 index 00000000..12cea907 Binary files /dev/null and b/docs/assets/model-form.png differ diff --git a/docs/assets/reversefloor.jpg b/docs/assets/reversefloor.jpg new file mode 100644 index 00000000..bdbce04d Binary files /dev/null and b/docs/assets/reversefloor.jpg differ diff --git a/docs/assets/rgb-sliders.png b/docs/assets/rgb-sliders.png new file mode 100644 index 00000000..6ff2593f Binary files /dev/null and b/docs/assets/rgb-sliders.png differ diff --git a/docs/assets/scale_paper.jpg b/docs/assets/scale_paper.jpg new file mode 100644 index 00000000..ea94b2b9 Binary files /dev/null and b/docs/assets/scale_paper.jpg differ diff --git a/docs/assets/solar-system-1.png b/docs/assets/solar-system-1.png new file mode 100644 index 00000000..86f6ea80 Binary files /dev/null and b/docs/assets/solar-system-1.png differ diff --git a/docs/assets/solar-system-3.png b/docs/assets/solar-system-3.png new file mode 100644 index 00000000..a99fdf24 Binary files /dev/null and b/docs/assets/solar-system-3.png differ diff --git a/docs/assets/solar-system-display-camera.png b/docs/assets/solar-system-display-camera.png new file mode 100644 index 00000000..e0ec247e Binary files /dev/null and b/docs/assets/solar-system-display-camera.png differ diff --git a/docs/assets/sub-craft.png b/docs/assets/sub-craft.png new file mode 100644 index 00000000..78b86660 Binary files /dev/null and b/docs/assets/sub-craft.png differ diff --git a/docs/assets/userflow.png b/docs/assets/userflow.png new file mode 100644 index 00000000..f79e6aa8 Binary files /dev/null and b/docs/assets/userflow.png differ diff --git a/docs/assets/view-form.png b/docs/assets/view-form.png new file mode 100644 index 00000000..20bce29c Binary files /dev/null and b/docs/assets/view-form.png differ diff --git a/docs/index.md b/docs/index.md index bf1530bc..1f4556f3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,92 +1,71 @@ - -!!! warning "Under Construction" - - We are constantly working on updating our documentation! -# Paper Playground +# Welcome to Paper Playground: Your Interactive Design Space [![GitHub](https://img.shields.io/badge/github-repo-yellow?logo=github&logoColor=white)](https://www.github.com/phetsims/paper-land/) [![Matrix Chat](https://img.shields.io/badge/matrix-chat-green?logo=matrix&logoColor=green)](https://matrix.to/#/#interactive-paper-programming:matrix.org) [![Youtube Channel](https://img.shields.io/badge/youtube-channel-red?logo=youtube&logoColor=red)](https://www.youtube.com/@PaperPlaygroundCommunity/) [![License](https://img.shields.io/github/license/phetsims/paper-land?color=blue)](./LICENSE) -## Interactive Play Meets Multimodal Web Development - -Paper Playground is an open-source project for collaboratively creating multimodal web experiences by means of mapping JavaScript code to real pieces of paper and manipulating the code in your **physical space**. Everything runs on your machine and you can collaborate locally or using a hosting service to collaborate over projects with others in your shared space. +Paper Playground is an open-source project for collaboratively creating multimodal web experiences by means of mapping code to real pieces of paper and manipulating the code in your **physical space**. Everything runs on your machine and you can collaborate locally or using a hosting service to collaborate over projects with others in your shared space. While Paper Playground can support many uses, our aim to support a community interested in bringing physical interaction as a means to collaboratively solve problems in codesigning technology. -Paper Playground is based on the [Paper Programs](https://paperprograms.org) open-source project and has been extended to incorporate [the library stack](https://github.com/scenerystack) used by [PhET Interactive Simulations](https://phet.colorado.edu) as a robust 2D scene creator and manager. The project focuses on enabling quick prototyping of web projects based in JavaScript. In creating Paper Playground, we are developing with a particular emphasis on easy addition of multimodal display such as audio features (like sounds and sonifications), speech description (both TTS engines and screen reader descriptions), and other non-visual features that are often difficult to design and develop alongside visual elements in complex web projects. +Paper Playground is based on the [Paper Programs](https://paperprograms.org) open-source project and has been extended to incorporate [SceneryStack](https://github.com/scenerystack), the development stack used by [PhET Interactive Simulations](https://phet.colorado.edu) as a robust 2D scene creator and manager. The project focuses on enabling quick prototyping of web projects based in JavaScript. In creating Paper Playground, we are developing with a particular emphasis on easy addition of multimodal display such as audio features (like sounds and sonifications), speech description (both TTS engines and screen reader descriptions), and other non-visual features that are often difficult to design and develop alongside visual elements in complex web projects. -## Overview of Paper Playground Use +### Overview of Paper Playground Components -The ideas behind Paper Playground are simple, but the possibilities are infinite. +Paper Playground is built around a few key components that work together seamlessly: -1. Using code or our low-code interface, Creator, create a project that factors in physical paper movement into the programs. -2. Print out the dot-covered papers assigned to those programs. -3. Put those *paper programs* in front of a webcam. -4. Interact with and experience the output of your programs in your browser or in the world around you using a projector (Display). -5. Add/remove/slide/rotate/add markers to programs and trigger the mappings between your papers position in space and your code! -6. Change your programs, iterate, and keep the creativity going! +- **Program Creation Systems**: Design and iterate on your programs with ease using abstracted program components in *Creator*. +- **Computer Vision**: Our tool detects your dot-encoded paper programs using a webcam, merging the digital and physical realms. +- **Execution and Display**: See your code come to life on screen, with outputs displayed in real-time. +- **Collaboration**: Shared databases allow for asynchronous collaboration, whether you’re working locally or online.
- ![Paper Playground setup detecting paper programs that create a moon lander and control vertical thrust](assets/full-interface.png){ width=900 } -
The interface in action.
+ ![(Left) Minimal configuration using Creator editor, detected wallet-sized papers, and displaying code output to an up-turned monitor. (Right) Same programs as above using letter-sized programs and visuals displayed using a mini-projector.](assets/configs-efh-horizontal.png) +
Flexible configurations for detecting paper programs and interacting with your code!
-You'll create JavaScript programs to populate a page (Display) with interactive, multimodal components to envision anything you want! - -Want to create a card game? Maybe an interactive art experience? Or maybe you want to prototype auditory displays (speech and sounds) for a project or idea that you have? It's all possible with Paper Playground. - -Every program you write is associated with a sequence of colored (black, red, green, and blue) dots that you will put (or print) on the corners of a piece of paper. We'll refer to the linked papers and code as paper programs from here on out! - -
- -
-
- -!!! note - This project retains the features of [Paper Programs](https://paperprograms.org). Refer to [Paper Programs documentation](https://github.com/janpaul123/paperprograms/blob/master/docs/) regarding legacy features (*including writing code for output to Projector*). - -### What do I do now? How do I create programs, detect programs, set up my camera and space, and make things happen? +You’ll interact with Paper Playground through three main interfaces: -See Setup section for installation and device setup instruction. See Documentation section for information on creating and using paper programs. +1. ***Camera***: Detects your paper programs using an attached camera device. +2. ***Interactive Display***: Shows the results of your programs, which can be interacted with virtually or projected. +3. ***Creator***: A low-code interface where you design your programs, step by step. -| Setup | Documentation | -| ----------- | ----------- | -| [Installation](./setup/install.md) | [Tutorial](./setup/tutorial.md) | -| [Device Setup](./setup/device-setup.md) | [Board API Documentation](./use/board-api.md) | -| [Device Recommendations](./setup/reqs.md) | [Example Paper Programs](./use/example-program.md) | -| [Creator Tutorial](./setup/creator.md) | [Model-View-Controller Framework](./use/mvc.md) | -| | [Resources and Downloads](./use/resources.md) | +### Getting Started with Your Design -## What is coming? +Check out the Getting Started section in the Navigation bar! We recommend reading the [Hardware Recommendations](./setup/reqs.md) first. In general, you will: -Our team is focused on a few large initiatives for integrating other projects into Paper Playground and for making it more friendly for non-technical, non-JavaScript users and designers. If these projects interest you, please join our community and take part in the development and discussion! +1. [**Set Up Your Workspace**](./setup/device-setup.md#setting-up-camera-and-projector-for-paper-detection): Open your interfaces. The Interactive Display can be set up on a separate monitor or projector, showing dot-encoded papers. +2. [**Calibrate the *Camera***](./setup/device-setup.md#color-calibrating-your-webcam-for-program-detection): Attach a webcam and adjust it according to your lighting conditions to ensure your dot-encoded papers are detected accurately. +3. [**Design with *Creator***](./setup/creator.md): Build your programs component by component, aligning with your creative vision. Each program gets a unique identity and sequence of dots for easy detection and interaction. -1. :robot: Using LLMs to support a user answer the question: "How do I turn my idea for a multimodal interactive into data variables, functions, and entire programs?". We are exploring generative models to support user creativity and engage iteratively toward outputting the full suite of programs for their project. - -2. :unlock: Abstracting the JavaScript code through means of an interface that assembles the components of your programs and highlights the relationships between your programs (e.g., At a quick glance, what information is needed and passed between programs?). - -3. :outbox_tray: Easier API integration for paper programs to control or output to other browser displays (besides our [scenery](https://github.com/phetsims/scenery)-focused Board and the legacy canvas-focused Projector), as well as new inputs such as microcontroller integration via Bluetooth and WebSockets. - -However, there are **many other areas** that the project can be expanded (see below for Contributing guidelines and suggestions)! +
+ ![Interfaces for Paper Playground. (Left) program detection and play area, Camera. (Middle) Code output and projection, Interactive Display. (Right) Program editor, Creator.](assets/all-interfaces-panel-horizontal.png) +
Interfaces for Paper Playground: (Left) program detection and play area, Camera. (Middle) Code output and projection, Interactive Display. (Right) Program editor, Creator.
+
-## Please, join our [Community](/docs/community.md) +**Bringing Paper Programs to Life**. After designing, print your paper programs. These can be detected by the *Camera* once in view, executing the associated code. Interact with your creations on the Interactive Display, manipulating papers to trigger events that dynamically update program components and outputs. -## Roadmap +**Dynamic and Collaborative Design**. Paper Playground supports an iterative design process. Make real-time updates in the *Creator* interface, see changes immediately on the Interactive Display, and collaborate with co-designers to refine your projects. This cycle encourages continuous creativity and improvement. -### Docs +**Enhancements for Inclusivity and Interaction**. Leveraging the open-source SceneryStack libraries, Paper Playground supports multimodal features like sound, pan and zoom, and alternative input. This makes your projects more accessible and interactive, enhancing the creative experience. -:books: Updated setup and tutorial! +**Flexible and Creative Setup Options.** Your paper programs can be any size, cut, folded, or decorated, allowing for diverse and flexible setup configurations. Whether you’re working with a desktop setup or projecting onto a wall, Paper Playground adapts to your creative environment. -### Tool +Paper Playground invites you to explore the boundaries of interactive design and collaboration. Whether you’re crafting educational tools, art installations, or experimental projects, this platform offers a unique space for your creativity to flourish. Start designing, collaborating, and seeing your ideas come alive in an interactive, dynamic environment. -:page_with_curl: More examples in the hosted database highlighting the power of multimodal design! +
+ ![Paper Playground setup detecting paper programs that create a submarine and control vertical position](assets/lunar-lander-craft.gif) +
Papercraft submarine controlling a virtual submarine!
+
-:computer: A UI for creating basic Papers without deep JavaScript knowledge! +## Community -:robot: Investigating use of LLMs to help users go from ideas to your suite of paper programs! +[🌍 Join the Community 🌍](community.md){ .md-button .md-button--primary } ## License -This software is licensed under the MIT license. For more information, see the [LICENSE](https://github.com/phetsims/paper-land/blob/main/LICENSE) file. +This software is covered under the [MIT License](https://github.com/phetsims/paper-land/blob/main/LICENSE). + +!!! note + This project retains the features of [Paper Programs](https://paperprograms.org). Refer to [Paper Programs documentation](https://github.com/janpaul123/paperprograms/blob/master/docs/) regarding legacy features (*including writing code for output to Projector*). diff --git a/docs/setup/CameraSelection.png b/docs/setup/CameraSelection.png new file mode 100644 index 00000000..3848e038 Binary files /dev/null and b/docs/setup/CameraSelection.png differ diff --git a/docs/setup/add-components.png b/docs/setup/add-components.png new file mode 100644 index 00000000..6cd02748 Binary files /dev/null and b/docs/setup/add-components.png differ diff --git a/docs/setup/camera-preview-markers.png b/docs/setup/camera-preview-markers.png new file mode 100644 index 00000000..3b023d11 Binary files /dev/null and b/docs/setup/camera-preview-markers.png differ diff --git a/docs/setup/connections.png b/docs/setup/connections.png new file mode 100644 index 00000000..90a624e5 Binary files /dev/null and b/docs/setup/connections.png differ diff --git a/docs/setup/controller-form.png b/docs/setup/controller-form.png new file mode 100644 index 00000000..c3e62d76 Binary files /dev/null and b/docs/setup/controller-form.png differ diff --git a/docs/setup/copy-delete-program.png b/docs/setup/copy-delete-program.png new file mode 100644 index 00000000..db65fae0 Binary files /dev/null and b/docs/setup/copy-delete-program.png differ diff --git a/docs/setup/create-from-template-button.png b/docs/setup/create-from-template-button.png new file mode 100644 index 00000000..c77cb7a6 Binary files /dev/null and b/docs/setup/create-from-template-button.png differ diff --git a/docs/setup/create-new-template.png b/docs/setup/create-new-template.png new file mode 100644 index 00000000..c66800cc Binary files /dev/null and b/docs/setup/create-new-template.png differ diff --git a/docs/setup/creator-create-component.png b/docs/setup/creator-create-component.png new file mode 100644 index 00000000..f561cf1d Binary files /dev/null and b/docs/setup/creator-create-component.png differ diff --git a/docs/setup/creator.md b/docs/setup/creator.md index dd976e0f..6a6e8867 100644 --- a/docs/setup/creator.md +++ b/docs/setup/creator.md @@ -3,225 +3,192 @@ !!! warning "Under Construction" We are working on updating our documentation - more details coming soon! - + ## What is Creator? !!! warning "In Development" The Creator interface is in development! The current feature set likely does not reflect the final vision of the tool. Follow the development in [GitHub](https://github.com/phetsims/paper-land) or in our community channels! -The primary vision of Creator is to bring the relationships between the components of your project to the forefront. The goal is to let you focus on the most important pieces and how they connect to your chosen interactions and outputs (sounds, speech, images, etc). +Creator is where you will add code to your paper programs before printing and playing with them in the *Camera*! The primary vision of Creator is to bring the relationships between the components of your project to the forefront, with significantly less code than using pure JavaScript. The goal is to let you focus on the most important pieces and how they connect to your chosen interactions and outputs (sounds, speech, images, etc). Making programs in Creator is organized around the Model-View-Controller (MVC) software design pattern. -Creator is organized around the [Model-View-Component framework](../use/mvc.md). +### What is MVC? -Simply stated: You create **Model components** (pieces of your idea that other components will need to use or change to make your project work), to be controlled by **Controller components** and display the information dynamically as a visual (e.g., text, image, shape), sound, speech, and more using **View components** +MVC stands for [Model-View-Controller](../use/mvc.md), a design pattern that divides your program into three interconnected components: -Watch the videos for two simple examples below for creating an "Audio Pendulum" or "Paper Organ". +- **Model**: This is the heart of your application, managing the data and logic. Think of it as the brain that knows everything but doesn't show anything. +- **View**: The View is all about presentation and user interface. It takes information from the Model and displays it in a way that you can understand and interact with. +- **Controller**: Acting as a bridge between you and the system, the Controller interprets user inputs and interactions, then decides what to do with them. -## Using Templates +This separation makes it easier to manage complex interactions, especially when changes in one area need to reflect in others. -You can load in templates using the New Template button in the top left of the interface. These will create a paper or set of papers that are pre-populated with components to create the desired effect. Want a shape that will follow the position of your paper? Select the *Movable Shape* template and the required papers/components will appear, ready to be customized! +In *Creator* you will **create programs**: Just like laying out papers on a desk, you can create, organize, and iterate on your programs within the *Creator* interface. Each program is like a piece of paper that you can move, collapse, or duplicate. Here you'll add components to your programs: -### Creating Templates +- **Model Components**: These are the building blocks of your application's logic and data. You'll define what each component does, how it interacts with others, and how it should be controlled. +- **View Components**: Decide how your application will present data and respond to user interactions. This could be through visuals, sounds, or even speech. +- **Controller Components**: These components are all about action. They determine how user inputs modify the Model or trigger changes in the View. -Some templates are already included in Paper Playground. However, if you'd like to use templates for common sets of programs/components +### Linking to the *Camera* Interface -## Copying Projects and Programs +!!! note inline end "Hide/Show dependency connections" + ![alt text](connections.png) +Once your program is set up, you can link it to the *Camera* interface by pressing the "Send to Playground" button at the top right of the LEFT PANE. Head over to *Camera* and interact with your programs as physical papers. Move them around, and see how they come to life, then come back to *Creator* to make changes! +### Visualizing Relationships -## Adding Images and Sounds +To keep track of how everything is connected, **dependencies** - components that rely on each other - are connected with colorful, dashed arrows. This, optional, visual cue helps you quickly anticipate how changes in one component might affect another or note missing pieces of your programs. They are broken into several categories depending on the components connected together. -Adding your own images (.jpg, .png, .gif, etc.) and sounds (.wav, .mp3, etc.) can be done right in Creator! Add a View Component, select Image or Sound, and drag/drop your file or select the upload box to open a file dialog. +## Example *Creator* Project: Audio Pendulum -Once uploaded, files will live in the paper-land directory under `.../www/media/images/upload` or `.../www/media/sound/upload`. You can also directly add files to this directory for bulk upload. +![alt text](../assets/creator-program-meta-data.png) -The files will now appear in the dropdown selection for those components! +We can illustrate the way programs are created, taking the 'Audio Pendulum' project as an example. Audio Pendulum is a simple interactive portraying a pendulum bob exhibiting periodic motion around an anchor, emitting a soft tone at its lowest point. -## Using AI chat to create Custom Code +The project utilizes several Model components: 'bobPosition' and 'anchorPosition' track the pendulum and anchor, 'period' defines the motion's frequency, and 'length' measures the distance from the bob to the anchor. -- +These components can be integrated into various programs. The project is designed to let users place the anchor and adjust the bob's position interactively. This setup requires two separate programs: one to map the anchor's position to a paper location, and another to set the bob's length based on its distance from another paper. -## Audio Pendulum Walkthrough -
- -
+Controller components 'bobController' and 'anchorPositionController' are used to animate the bob and set the anchor's position, respectively. Additionally, View components create the visual (like circles for the bob and anchor using shape components) and auditory elements (a 'bobSound' function calculates timing of the tone trigger based on the bob's swing position). + +**Watch the steps to create Audio Pendulum and the project in action in these videos:**
- +
-## Paper Organ Walkthrough
- +
+## Adding Model, View, and Controller Components to your Programs + +{Content coming soon!} + +### Component Details +=== "Model Components" + There will be info on each component in here. Including Arrays and array items! + + ![alt text](../assets/model-form.png) + +=== "View Components" + There will be info on each view component in here. + + ![alt text](view-form.png) + + **Adding Images and Sounds** + + Adding your own images (.jpg, .png, .gif, etc.) and sounds (.wav, .mp3, etc.) can be done right in *Creator*! Add a View Component, select Image or Sound, and drag/drop your file or select the upload box to open a file dialog. + + Once uploaded, files will live in the paper-land directory under `.../www/media/images/upload` or `.../www/media/sound/upload`. You can also directly add files to this directory for bulk upload. + + The files will now appear in the dropdown selection for those components! + +=== "Controller Components" + There will be info on each controller component in here. + + ![alt text](controller-form.png) + + ## Paper Controller Components - What can I use to trigger code in my paper programs?** + + !!! inline end tip + For advanced users or when using Custom Code, see the [paperLand API](../use/board-api.md) for all paper events. + + ### Paper Movement + + {Content coming soon!} + + ### Paper Markers + + {Content coming soon!} + + ### Whiskers - Paper Proximity + + {Content coming soon!} + +### (Custom Functions) Customizing Component Output + +{Content coming soon!} + +### Adding Connections (component dependencies) + +{Content coming soon!} + +![alt text](add-components.png) + +#### Dependency or Reference? + +{Content coming soon!} + +![alt text](custom-function.png) - \ No newline at end of file +## Using AI chat to create custom component logic and output + +{Content coming soon!} + +![alt text](../assets/ai-example.png) + +## Custom Code + +{Content coming soon!} + +## Organizing Programs + +{Content coming soon!} + +![alt text](copy-delete-program.png) + +## Managing Projects + +![alt text](spaces-and-projects.png) + +As mentioned in the [Tutorial](./tutorial.md#organizing-your-code-spaces-and-projects), Projects exist to organize your paper programs in *Creator* only. Sending a project "to the Playground" will *overwrite the active set of papers* for that `space`. + +Think of Projects as your way of managing similar sets or variants of sets of paper programs. Perhaps you want to use it as version control? Maybe you want to aggregate sets of papers that have a theme? It's up to you. Just make sure you send the project you would like to play with to the *Camera* with Send to Playground, or you might be a bit confused when your papers do something you don't expect or nothing at all! Use the **New Project** button to get going. + +We recommend using the **Copy Project** feature whenever you are looking to start a variant of an existing project (whether it is read-only or you really just don't want to break your existing project). **Note: When you create a project in the `space` you are currently in, you will need to leave the space and re-enter (or refresh the Creator page) to see it appear in the list of projects for that space.** + +### Downloading and Loading Projects + +{Content coming soon!} + +## Using Templates + +You can load in templates using the "Create from Template" button in the top left of the interface. These will create a paper or set of papers that are pre-populated with components to create the desired effect. Want a shape that will follow the position of your paper? Select the *Movable Shape* template and the required papers/components will appear, ready to be customized! + +![alt text](create-from-template-button.png) + +!!! warning "Note" + At this time, all imported templates are created as new programs. If you'd like to integrate them into existing programs, import the templates into your project and use them as a reference for creating new component in your existing paper programs. + +### Creating Templates + +Some templates are already included in Paper Playground. However, if you'd like to use templates for common sets of programs/components, you can create them globally for all `spaces` or on a per-`space` basis. *Templates exist in their own database separately from the spaces that contain your paper programs.* + +#### Creating New Templates + +1. Create a new project in the space of your choice (the `templates` space is the best choice if using our hosted program database). +2. Create your programs! Populate them with the necessary components to create a self-contained fully functioning (set of) program(s). +3. Open the "Edit Templates" collapsible menu on the RIGHT PANE. +4. Make sure you have "New Template" selected from the dropdown. Selecting an existing template will overwrite the programs in the LEFT PANE! +5. Enter a name, description, and a few comma separated keywords. +6. Save the Template for globally for all `spaces` or just locally in the `space` you are currently in. +7. That's it! Check it's been created by using the "Create from Template" button. + +![alt text](create-new-template.png) + +#### Editing Templates + +1. Open your template from the "Edit Templates" collapsible menu ( :danger: this will override any program you current have in the LEFT PANE!) +2. Make any changes to your programs and their components. You can also edit the Template name and description. +3. Save changes! + +![alt text](edit-template.png) + +## More walkthroughs + +### Paper Organ Walkthrough + +
+ +
diff --git a/docs/setup/custom-function.png b/docs/setup/custom-function.png new file mode 100644 index 00000000..ee1b9c8a Binary files /dev/null and b/docs/setup/custom-function.png differ diff --git a/docs/setup/device-setup.md b/docs/setup/device-setup.md index 3179246f..c9da78d4 100644 --- a/docs/setup/device-setup.md +++ b/docs/setup/device-setup.md @@ -4,12 +4,11 @@ We're currently updating our documentation. Stay tuned for more details! - This page will guide you through setting up your devices so your computer can detect your printed paper programs and you can (optionally) project visuals onto them! If you're already setup, then head over the [Tutorial](../setup/tutorial.md) for a run-down of the interface and how to get started making programs! -## Board Projector Setup +## *Interactive Display* Projector Setup If you are only using the paper program detection capabilities of Paper Playground and planning to use Preview papers (eye icon next to programs in the Camera interface), skip to [Camera Setup](#camera-setup). @@ -21,33 +20,33 @@ Find a place to place your projector that will let you move your paper programs You may later find that you need to adjust the relative positions of your projector and webcam in order to get the best program detection and most space to move papers around. See [Fine-tuning program detection](#fine-tuning-program-detection) and [Webcam tips](#webcam-optimization-tips) for more advice on improving program detection. -After powering on your projector and connecting it to your computer, open the Board interface (board.html) in a separate window and move it into the projector window. +After powering on your projector and connecting it to your computer, open the *Display* interface (board.html) in a separate window and move it into the projector window. Now it's time to setup your webcam. ### Camera Setup -### Camera Configuration +#### Camera Configuration An external USB webcam (at least 720p) is the best to use for flexibility in your paper-moving play space. Try pointing the webcam down so you can naturally move papers around without worrying about working against gravity. Webcam/projector configurations parallel to the floor (e.g., pointing at a wall) are possible, especially using tape, sticky tack, or magnets (in the case of e.g., a whiteboard). Many configurations are possible! The farther away the webcam from the surface you'll be moving the papers, the larger you will want your papers/dots to be. You may also notice a difference in detection accuracy with higher resolution cameras (1080p and above). -### Opening the Camera interface +#### Opening the Camera interface After setting up the hardware, navigate to [http://localhost:3000/camera.html](http://localhost:3000/camera.html) for camera calibration. Grant the browser permission when prompted for camera access. !!! failure "Camera not detected" - If your camera is not detected or not presented as an option under the Devices header on the Camera page sidebar (only viewable if more than one camera device is detected), then try checking your USB connection. If you're still having problems, it may be a permissions issue from your browser. You will need to access the site settings for localhost. This varies per browser. In Chrome, you can select the icon to the left of the URL and select "Site Settings". From there, you can navigate to Camera permissions and change it from Ask (Default) to Allowed. + If your camera is not detected or not presented as an option under the Devices header on the Camera page sidebar, then try checking your USB connection. If you're still having problems, it may be a permissions issue from your browser. You will need to access the site settings for localhost. This varies per browser. In Chrome, you can select the icon to the left of the URL and select "Site Settings". From there, you can navigate to Camera permissions and change it from Ask (Default) to Allowed. -### Aligning your projector to the Camera view +![alt text](CameraSelection.png) -![Initial camera screen view](img/camera-screen.png) +#### Aligning your projector to the Camera view -Project any vibrant, full-screen image. The Board interface can work, but you will have an easier time with a bright white screen (assuming a black background). +Project any vibrant, full-screen image. The *Interactive Display* interface can work, but you will have an easier time with a bright white screen (assuming a black background). -![Camera screen with set boundaries](img/camera-boundaries.png) +![alt text](../assets/Camera-efh.png) In the camera view, you'll notice **4 red circles** at the corners: **TL, TR, BR, BL**. Drag these circles to align with the projection's corners. If done accurately, this synchronizes the camera and projector views so that any visuals projected on the paper will properly align based on the coordinates you define in your programs. @@ -63,17 +62,19 @@ If you need to zoom in or drag the camera view to find the red circles or to hel When you are ready to project, press the "Projector Mode" button on the Board interface to enlarge the display to the entire projector window. By default, the screen is black. -### Color calibrating your webcam for program detection +#### Color calibrating your webcam for program detection For color calibration, print one of your paper programs and position the printed page within the camera's view. (if using the projector, it might be easier to turn off the projector or project a black screen during this step.) +![alt text](../assets/Calibration.png) + On the camera view, circles will overlay the printed ones if they are detected. Calibrate each color (R, G, B, D) individually by selecting the color from the sidebar and then clicking its corresponding circle in the camera view. When selecting the color on the sidebar, the circle will highlight. The highlight will disappear when it successfully calibrates. You may need to click a few times on the circle in the Camera view depending on page performance. ![Camera view during calibration](img/camera-calibrating.png) Post-calibration, the dot colors in the sidebar might slightly differ, reflecting the camera's adaptation to your space's lighting. If lighting changes, recalibrate. It's important to maintain steady light conditions. Sunlight changes rapidly, especially with passing clouds! If you can, find a room with steady, uniform illumination or recalibrate frequently. -#### Calibrating for markers +##### Calibrating for markers Calibration also sets the average dot size. This will determine how large dots need to be to be considered "markers". If you wish to use markers in your programs, the dots will need to be 3 times larger by default. @@ -125,16 +126,16 @@ Look under the Detection header in the sidebar of Camera.html and adjust the con - **Pixel Value Threshold:** Changes the number of steps used to check for a difference between a dot and background. Large steps might miss dots without enough contrast, but will increase performance. Small steps will find more dots, but slow down performance significantly. - **Min Pixel Value:** The minimum saturation value (out of 256) to look for a dot. Use this to gate out noise if image features are being detected as dots. -- **Max Pixel Value:** The maximum saturation value (out of 256) to look for a dot. Use this to gate out noise if image features are being detected as dots. +- **Max Pixel Value:** The maximum saturation value (out of 256) to look for a dot. Use this to gate out noise if image features are being detected as dots. - **Min Dot Area (pixels):** The minimum area in pixels that an image feature must be to be called a dot. Use this to gate out noise if image features are being detected as dots. - **Max Dot Area (pixels):** The maximum area in pixels that an image feature must be to be called a dot. Use this to gate out noise if image features are being detected as dots. *This is a good slider to use if image features are being erroneously detected as Markers*. - **Min Dot Separation (pixels):** The minimum numbers of pixels the algorithm expects to see dots. Lower values will help to detect smaller dots or farther away programs, at the cost of detecting more image features that may not be paper dots. - **Scale Factor:** Recommended to keep at 1. Higher values lower the effective resolution of your camera feed. If you need higher performance and dot detection is not a problem/you are using a very high resolution camera, this will speed up the algorithm significantly to get more performance. -## Canvas Projector Setup +![alt text](../assets/DetectionParameters.png) -If you're using the legacy Canvas (projector.html) page to send visual elements to the web canvas, rather than the Display (board.html), you'll follow these intructions instead: - -Power on the projector and separate [http://localhost:3000/projector.html](http://localhost:3000/projector.html) to its own window. Move this window to the projector's display and enter fullscreen mode (Ctrl/Cmd+Shift+F). If you encounter issues (e.g., a recently created program not displaying), refreshing the page should help. +## Canvas Projector Setup +If you're using the legacy Canvas (projector.html) page to send visual elements to the web canvas, rather than the Display (board.html), you'll follow these instructions instead: +Power on the projector and separate [http://localhost:3000/projector.html](http://localhost:3000/projector.html) to its own window. Move this window to the projector's display and enter fullscreen mode (Ctrl/Cmd+Shift+F). If you encounter issues (e.g., a recently created program not displaying), refreshing the page should help. \ No newline at end of file diff --git a/docs/setup/edit-template.png b/docs/setup/edit-template.png new file mode 100644 index 00000000..63b11d87 Binary files /dev/null and b/docs/setup/edit-template.png differ diff --git a/docs/setup/spaces-and-projects.png b/docs/setup/spaces-and-projects.png new file mode 100644 index 00000000..0ed0f265 Binary files /dev/null and b/docs/setup/spaces-and-projects.png differ diff --git a/docs/setup/tutorial.md b/docs/setup/tutorial.md index e61f9feb..7b81f902 100644 --- a/docs/setup/tutorial.md +++ b/docs/setup/tutorial.md @@ -1,29 +1,28 @@ # Using Paper Playground -!!! warning "Under Construction" - - We are working on updating our documentation - more details coming soon! - -Before we begin, make sure you have [installed Paper Playground](../setup/install.md) and [set up your camera](../setup/device-setup.md). +Before we begin, make sure you have [installed Paper Playground](../setup/install.md) and [set up your equipment](../setup/device-setup.md). ## Interface Overview and Startup +!!! abstract inline end "User Flow" + ![alt text](../assets/userflow.png) + ### Step 1: Open up all pages of the interface Navigate to localhost:3000 in your browser and either click the links or open in your browser: -1. Camera.html -2. Projector.html -3. Board.html -4. Creator.html +1. Camera (camera.html) +2. Canvas (projector.html) +3. Interactive Display (board.html) +4. Creator (creator.html) ### What is the Camera page? The Camera page is where all the action happens for turning your paper programs interactive! -![Camera Interface](../assets/camera-page.png) +![Camera Spaces](../assets/camera-spaces-tab.png) On this page you will find the preview of your webcam, a preview of the full JavaScript for your currently selected paper program, and a plethora of options in the sidebar. Explore the headings in the sidebar to create and navigate between [spaces](#what-is-a-space), [calibrate your webcam](../setup/device-setup.md#color-calibrating-your-webcam-for-program-detection) to detect paper programs, print and [virtually preview programs and markers](#what-are-preview-papers-eye), and [fine-tune your detection](../setup/device-setup.md#fine-tuning-program-detection). @@ -45,15 +44,19 @@ While a lot more can be done to help the preview papers mimic how you can move a - Preview papers can be removed at any time by selecting the red square. !!! tip - If you'd like to quickly clear the Preview programs, the best option currently is to refresh the Camera page. -##### Preview Markers +##### Preview Markers :red_circle: :green_circle: :blue_circle: :black_circle: Just like preview papers, you can simulate physical paper markers under the Preview Markers sidebar menu. Select the eye icon to place a draggable marker into the camera view that triggers marker-related code in your paper programs. ![Marker Previews](../assets/camera-preview-markers.png) +
+ +
+
+ ### Organizing your code: Spaces and Projects #### What is a Space? @@ -61,11 +64,8 @@ Just like preview papers, you can simulate physical paper markers under the Prev A space is way of organizing your programs and how you'll locate your programs in the Camera interface to run them. Some software might refer to this as a "workspace", but we prefer to think of it as a playspace! !!! warning - At the time of writing, Spaces can only be created from the Camera interface ("Add New Space" button). You can select, but not create, Spaces in the Creator interface. -![Camera Spaces](../assets/camera-spaces-tab.png) - All of the programs in a space can be for one project or you can create a series of simpler programs that all exist in the same Space. This is completely up to you and we use them for both purposes. There is no limit to the number of Spaces you can have, so focusing each Space on one idea works well. You might create your own personal space "my-space" :wink: and fill it with ideas you have or create a "frogger-game" space and collect all of the paper programs that will work together to create your project. @@ -73,13 +73,11 @@ You might create your own personal space "my-space" :wink: and fill it with idea ##### What is a Creator Project? !!! info - If you are not familiar with JavaScript development, we highly recommend you begin with the Creator interface! When working from the Creator interface, you may notice you can create Projects after selecting space. This is one level deeper than a Space and allows you to have multiple version or different sets of programs that you can send to the selected Space in the Camera interface via the **Send to Playground** button. !!! danger "Don't lose your programs!" - If you select **Send to Playground** for your current project, it will OVERWRITE the programs in the Space. This introduces some incompatibility between editing programs directly in the JavaScript Editor (editor.html) and in Creator. If you only work in Creator and regularly **Save Project**, then you can always select your project and your work will be there. *If you'd like to directly write JavaScript and Creator, use the Custom Code button on your paper program in Creator. This code will be added to the end of each listed event function in the interface (e.g., onProgramAdded).* @@ -96,10 +94,9 @@ There are a few helpful additions to this page to help with your creation and pl ##### Position Interval -You can adjust the sensitivity of your programs to paper movement (in the event of detection jitter) by moving the **Position Interval** slider to the right of the Board display. +You can adjust the sensitivity of your programs to paper movement (in the event of detection jitter) by moving the **Position Interval** slider to the right of the *Interactive Display*. !!! warning - Keep this value as low as you can. At high values, your paper will be able to move very far without the program recognizing it has moved. Values as low as **0.1-0.2** work in many cases. ##### Print Speech @@ -112,7 +109,7 @@ Regular JavaScript usage of `console.log` will display in your browser's develop ### What is the Canvas page? -At this time, given the legacy structure of the client, all of the code detected in the Camera is executed through the Canvas. However, in Paper Playground, all development has been focused on paper program output sent to the Display. +At this time, given the legacy structure of the client, all of the code detected in the Camera is executed through the Canvas. However, in Paper Playground, all development has been focused on paper program output sent to the Display. **The Canvas page must be opened to run the code, *but the tab or window does not need to be visible.*** @@ -138,11 +135,11 @@ Open that link (make sure you keep the Camera page open at all times) and select ![The program editor](../assets/editor-example.png) -Make some changes in the editor (try changing what text gets drawn on the canvas for starters) and click the "save" button. The changes should now be reflected in the output of the Board or Projector pages. +Make some changes in the editor (try changing what text gets drawn on the canvas for starters) and click the "save" button. The changes should now be reflected in the output of the *Display* or Projector pages. When you're ready to print that program as a real piece of paper, click the Printer icon beside the program name on the Camera page. Place the newly printed paper in your webcam's view. !!! note Paper Playground looks for a comment on the first line of the file and uses that as the program's name. It will use the keywords on the second line for search purposes. -At this point you should have everything you need to start building a collaborative Paper Playground "play" Space and a working interactive paper program experience! Look at the [Board API reference](../use/board-api.md) for more information about the functions available to your programs. +At this point you should have everything you need to start building a collaborative Paper Playground "play" Space and a working interactive paper program experience! Look at the [paperLand API reference](../use/board-api.md) for more information about the functions available to your programs. diff --git a/docs/setup/view-form.png b/docs/setup/view-form.png new file mode 100644 index 00000000..20bce29c Binary files /dev/null and b/docs/setup/view-form.png differ diff --git a/docs/use/mvc.md b/docs/use/mvc.md index e44641f1..0646ce96 100644 --- a/docs/use/mvc.md +++ b/docs/use/mvc.md @@ -1,11 +1,11 @@ -# Model-View Separation +# Model-View-Controller Framework -!!! warning "Under Construction" - - We are working on updating our documentation - more details coming soon! +The Model-View-Controller (MVC) framework organizes a program into three core segments: the Model, which manages the logic and data; the View, which handles the user interface and presentation; and the Controller, which interprets user inputs and interactions. By utilizing the MVC framework, we aimed to clarify the relationships between these components, specifically focusing on how changes in one segment drive updates in others. The approach involves building Model components that, when updated, trigger changes in other Models or Views, with these updates typically initiated through interactions with a Controller component. -Paper Land code encourages a software design pattern called "model-view separation". This pattern -is often used to develop user interfaces, games, and is heavily used by PhET libraries. +## Model-View Separation + +Paper Playground (paper-land/paperLand) code encourages a software design pattern called "model-view separation". This pattern +is often used to develop user interfaces, games, and is heavily used by [SceneryStack](https://scenerystack.github.io/community/) libraries. Benefits of model-view separation include: @@ -31,7 +31,7 @@ for far more than user interface development! ## Example Paper Land model -Let's pretend we want to display a cupcake 🧁 on the Paper Land Board. On the Board, we want to display a visual +Let's pretend we want to display a cupcake 🧁 on the Paper Land Display. On the Display, we want to display a visual cupcake and write strings that describe its properties. First, lets consider the important things to draw and describe about the cupcake. That will determine the components we @@ -66,14 +66,14 @@ this: Quickly breaking down the numbered sections of the above Program code: -1) `addModelComponent` is used to add new components to the Board model. We provide the name for the component so that +1) `addModelComponent` is used to add new components to the Display model. We provide the name for the component so that it can be looked up later, and the actual model component. The model component can be any data type. In this example, we are using a PhET library component called `axon.Property`. `axon.Property` has support for sending events whenever the value changes. We will use that later to update cupcake descriptions when values change! 2) Boilerplate that tells Paper Land to create these model components when this Program is detected. NOTE: In a real example, it would be important to remove the model components when the program is removed. See -[Board API](https://github.com/phetsims/paper-land/blob/main/docs/use/board-api.md). +[Display API](https://github.com/phetsims/paper-land/blob/main/docs/use/board-api.md). ## Example Paper Land view @@ -121,11 +121,11 @@ Quickly breaking down the numbered sections of the above Program code: 1) We create a `CupcakeNode` and add it to the scene. The `CupcakeNode` could use scenery to draw the cake, icing, and sprinkles and have other structure for a screen reader but that is beyond the scope of these notes. The `cupcakeNode` - is added as a child to the scene so that it is drawn to the Board. + is added as a child to the scene so that it is drawn to the Display. 2) We add a link to the `cakeTypeProperty` with `addModelPropertyLink`. The first argument is the name of the Property to observe. The second argument is the work you want to do when the Property value changes. `addModelPropertyLink` will handle listener registration for you so that it works no matter what order the model and view code is introduced - to the Board. + to the Display. 3) This is the logic called whenever the model `cakeTypeProperty` changes. I introduced imaginary `drawChocolate`, `drawCarrot` and `drawLemon` functions. Implementing these is beyond the scope of these notes, but you could imagine they change images or colors representing the cupcake. They are followed by code @@ -136,4 +136,4 @@ From a single `cakeTypeProperty`, we support several output modalities. You can Programs that could play sounds, trigger vibrations, and many other things from this single model component. NOTE: In a real example, it would be important to remove the model components when the program is removed. See -[Board API](https://github.com/phetsims/paper-land/blob/main/docs/use/board-api.md). \ No newline at end of file +[Display API](https://github.com/phetsims/paper-land/blob/main/docs/use/board-api.md). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 07165543..e27ce15d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -121,14 +121,14 @@ markdown_extensions: nav: - Home: index.md - Getting Started: - - Hardware Recommendations: setup/reqs.md - - Step 1 Installation: setup/install.md - - Step 2 Device Setup: setup/device-setup.md - - Tutorial: setup/tutorial.md + - 1. Hardware Recommendations: setup/reqs.md + - 2. Installation: setup/install.md + - Device Setup: setup/device-setup.md + - Interface Overview: setup/tutorial.md - Creator Tutorial: setup/creator.md - Resources: - Model-View-Controller Framework: use/mvc.md - - paper-land API: use/board-api.md + - paperLand API: use/board-api.md - Design Tips: use/designing-programs.md - Example Papers (deprecated): use/example-program.md - Downloadables: use/resources.md