memgonzales / aniframe-language

Domain-specific language for two-dimensional drawing and frame-based animation for novice programmers

AniFrame

AniFrame is an open-source domain-specific language for two-dimensional drawing and frame-based animation for novice programmers.

This work was awarded Best Student Paper at the 24^th Philippine Computing Science Congress (PCSC 2024), held in Laguna, Philippines.

• Our preprint can be accessed via this link.
• Our PCSC 2024 slides can be accessed via this link.

If you find AniFrame useful, please consider citing:

@inproceedings{aniframe2024,
  title        = {AniFrame: A Programming Language for 2D Drawing and Frame-Based Animation},
  author       = {Gonzales, Mark Edward M. AND Ibrahim, Hans Oswald A. AND Ong, Elyssia Barrie H. AND Fernandez, Ryan Austin},
  year         = 2024,
  month        = {May},
  booktitle    = {24th Philippine Computing Science Congress (PCSC 2024)},
  publisher    = {Computing Society of the Philippines}
}

Table of Contents

• ⚙️ Installing AniFrame
• 🚀 Running AniFrame Code
• 📚 Description
• 📒 Language Documentation
• 🖼️ Gallery
• 💻 Authors

⚙️ Installing AniFrame

System Requirements

• Operating System: Windows, macOS, or Linux
• Storage: ~1.8 GB

Option 1: Using Docker (Recommended)

The simplest way to install AniFrame is via Docker. This installation bundles AniFrame's interpreter and browser-based environment where you can write and run code.

1. Download and install Docker, a platform for building and running containerized apps:

   • [For macOS and Windows] Install Docker Desktop.
   • [For Linux] For easier installation, we recommend installing Docker Engine instead of Docker Desktop. Instructions for different Linux distributions can be found here.

2. Start the Docker daemon:

   • [For macOS and Windows] Open Docker Desktop to start the daemon.
   • [For Linux] Follow the instructions here.

3. Launch a terminal (from anywhere), and pull the latest version of AniFrame by running:

   docker pull ghcr.io/memgonzales/aniframe:latest
   

4. Create a folder named aniframe-code anywhere in your computer. Inside this folder, create an empty file named sample.js.

5. Spin up a container by running;

   docker create --name aniframe -p 8000:8000 -p 8080:8080 -v path/to/aniframe-code/sample.js/in/your/computer:/app/browser/p5-widget/p5.js-widget/static/sample.js ghcr.io/memgonzales/aniframe:latest
   

   Replace path/to/aniframe-code/sample.js/in/your/computer with the path to the sample.js file that you created in the previous step. It may be more convenient to use the absolute path. If you are using Windows, make sure to replace the backward slashes (\) in the path with forward slashes (/).

6. Launch a terminal (from anywhere), and start the AniFrame container by running:

   docker start aniframe
   

7. Open a shell inside the container by running:

   docker exec -it aniframe bash
   

8. Inside this shell, run the following command:

   sh start-django.sh && exit
   

9. To open the environment where you can write and run AniFrame code, visit http://localhost:8000 on your browser.

Option 2: Using Conda

Click here to show/hide instructions for installing AniFrame via Conda.

1. Clone this repository by running:

   git clone https://github.com/memgonzales/aniframe-language
   

2. Create a virtual environment with the dependencies installed via Conda (we recommend using Miniconda):

   cd aniframe-language
   conda env create -f environment.yaml
   

3. Activate this virtual environment by running:

   conda activate aniframe
   

4. The instructions above cover the installation of AniFrame's interpreter and part of its browser-based environment.

   Follow the instructions here to finish configuring the browser-based environment.

↑ Return to Table of Contents.

🚀 Running AniFrame Code

If you installed AniFrame via Docker

1. Every time you want to use AniFrame, perform the following steps first:

   • Launch a terminal (from anywhere). Start the AniFrame container and open a shell inside it by running:

     docker start aniframe
     docker exec -it aniframe bash
     

     Doing so should change the working directory to root@<conainer_id>:/app/browser/p5-widget/p5.js-widget.

   • Enable cross-origin resource sharing (CORS) following the instructions here.

2. Visit http://localhost:8000 on your browser.

3. Write the AniFrame code on the text editor at the left side of the webpage.

   For a quick start, you can refer to sample AniFrame source code here.

4. Once you are done writing your code, click the Submit button.

   Doing so should open a window prompting you to select a folder. Select the aniframe-code folder that you created when installing AniFrame. If your browser prompts you to allow AniFrame to view files and save changes to this folder, grant these permissions.

5. On the shell you opened in Step 1 (i.e., the shell with working directory root@<conainer_id>:/app/browser/p5-widget/p5.js-widget), run:

   sh run-code.sh
   

   The text output of your code will be displayed on this terminal.

6. Navigate back to your browser, and click the Reset button.

   The visual output of your code will be displayed on the player at the right side of the webpage.

   If no output is displayed, check if you properly enabled CORS (see instructions here).

   

7. Once you are finished using AniFrame:

   • On the shell you opened in Step 1 (i.e., the shell with working directory root@<conainer_id>:/app/browser/p5-widget/p5.js-widget), run:

     exit
     

     Doing so should return you to your usual terminal.

   • Run the following command to stop the AniFrame container:

     docker stop aniframe
     

If you installed AniFrame via Conda

Refer to the instructions here.

↑ Return to Table of Contents.

📚 Description

Creative coding is an experimentation-heavy activity that requires translating high-level visual ideas into code. However, most languages and libraries for creative coding may not be adequately intuitive for beginners. Designed for novice programmers, AniFrame's core principles and features are as follows:

• Ready Support for Animation-Specific Constructs. AniFrame features animation-specific data types (e.g., for drawn objects and colors), operations (e.g., for mixing colors and simplifying the layering of objects into composite objects), and built-in functions for shapes and affine transformations.
• Fine-Grained Control Over Animation. AniFrame adopts a frame-based strategy where programmers explicitly specify the object to be animated, along with the start and end frames for the animation sequence. Settings such as the frame rate and the total number of frames can also be configured.
• Reduced Learning Curve. AniFrame follows a Python-like syntax, limits the number of keywords and control structures to a minimum, and tries to use keywords that are close to their semantic intent (e.g., Text instead of string). Specifying data types is optional since type inferencing is enforced.
• Computational Expressivity. AniFrame supports common mathematical operations, built-in trigonometric functions, and user-defined recursive functions. Their utility is demonstrated in creating self-similar patterns, such as fractals.

↑ Return to Table of Contents.

📒 Language Documentation

Refer to https://aniframe-docs.vercel.app/

↑ Return to Table of Contents.

🖼️ Gallery

We'd love to showcase your creative coding artwork here!

Code	Result	Code	Result
Jumping Shapes		Smaller and Smaller Circles
A Pink Round Hero		Pinocchio

↑ Return to Table of Contents.

💻 Authors

• Mark Edward M. Gonzales
  [e-mail]
  

• Hans Oswald A. Ibrahim
  [e-mail]
  

• Elyssia Barrie H. Ong
  [e-mail]
  

• Mr. Ryan Austin Fernandez
  [e-mail]
  

This is the major course output in a theory of programming languages class for master's students under Mr. Ryan Austin Fernandez of the Department of Software Technology, De La Salle University. The task is to create a domain-specific programming language within ten weeks.