Getting Started

Basic Example

To give you a rough idea of the structure of JAnim, you can create a new file called learn.py in your folder.

Then copy the following code into the file:

HelloJAnimExample 
from janim.imports import *

class HelloJAnimExample(Timeline):
    def construct(self):
        # define items
        circle = Circle(color=BLUE)
        square = Square(color=GREEN, fill_alpha=0.5)

        # do animations
        self.forward()
        self.play(Create(circle))
        self.play(Transform(circle, square))
        self.play(Uncreate(square))
        self.forward()

Next, in the command line, use

janim run learn.py HelloJAnimExample

A window will pop up, displaying content that should match the video above.

This window is set to be on top by default, which you can disable from the menu bar.

Now, let’s take a closer look at what this code does:

from janim.imports import *

Here, we import the main features of JAnim, allowing us to use them later.

class HelloJAnimExample(Timeline):
    def construct(self):

These two lines define a class HelloJAnimExample inheriting from Timeline, and implement the construct() method, where the animation content is written.

HelloJAnimExample can be named whatever you like.

Tip

If you’re confused by these two lines, you can memorize them as a standard step.

Of course, replace HelloJAnimExample with your desired name.

Let’s continue to the specific animation part.

circle = Circle(color=BLUE)
square = Square(color=GREEN, fill_alpha=0.5)

These two lines define a circle and a square (by default, not filled inside).

The circle is set to blue;
The square is set to green with 50% opacity fill.

At this point, these objects haven’t been displayed yet. Let’s look at the next few lines.

self.forward()
self.play(Create(circle))
self.play(Transform(circle, square))
self.play(Uncreate(square))
self.forward()

Here is the code that produces the animation, in order:

  • self.forward() advances 1 second; since no objects are displayed at this time, this second is just a blank background.

  • self.play(Create(circle)) plays the circle creation animation

  • self.play(Transform(circle, square)) plays the interpolating animation from the circle to the square.

  • self.play(Uncreate(square)) plays the square disappearing animation.

  • self.forward() advances 1 second, similar to the previous one.

Among them:

  • forward() keeps the same frame for a period, default is 1 second, you can also specify the seconds.

  • play() basic format is self.play(animation object), making the animation last for a period.

For example, you can add duration=2 to the transformation line.

self.play(Transform(circle, square), duration=2)

Then the animation process will last for 2 seconds.

Items

In the example above, we have two items: Circle and Square, which are essentially geometric items.

Components

Important

For items, there is an important concept called “components”.

Each item contains several components, for example, geometric shapes are represented by “outline points”.
Therefore, for geometric items, these are its components:

  • Outline coordinates points

  • Stroke width radius

  • Stroke color stroke

  • Fill color fill

To manipulate components, you need item.component_name.function(), for example:

circle.fill.set(RED, 0.5)

This line sets the fill color of the circle to red with 50% opacity; you can insert this line right after circle = Circle(color=BLUE) in the above example to see the effect.

Similarly, circle.stroke.set(...) will set the stroke color.

Hint

If you want to set both the stroke and fill color, you don’t have to write:

circle.stroke.set(RED)
circle.fill.set(RED)

As a simpler way, you can write the above two lines as:

circle.color.set(RED)

Here, a single color is provided to manipulate both stroke and fill.

Initialization Parameters

Remember the code from the earlier example?

# define items
circle = Circle(color=BLUE)
square = Square(color=GREEN, fill_alpha=0.5)

This code does not seem to manipulate the components of circle, so how are these items’ colors set?

You might have noticed the parameters passed to Circle and Square, color=XXX and fill_alpha=XXX.

Specifically, setting component properties at the time of item creation doesn’t need to be listed line by line, they can all be written as parameters directly. Here are some properties available for geometric items:

  • stroke_radius: Stroke thickness

  • color: Stroke and fill color

  • stroke_color: Stroke color, will override color

  • fill_color: Fill color, will override color

  • alpha: Opacity, 1 means fully opaque, 0 means fully transparent, numbers between 0~1 mean semi-transparent.

  • stroke_alpha: Stroke opacity, will override alpha

  • fill_alpha: Fill opacity, will override alpha

Component Animation

From the previous study, we know that by

circle.color.set(RED)

we can set the circle to red.

This setting is immediate, but if written like this:

circle.anim.color.set(RED)

Notice the difference is adding .anim before the component manipulation.

This writing creates an animation transitioning from the original color to red, which can be placed in self.play(...) to display the animation.

For example, the following code:

CmptAnimExample 
from janim.imports import *

class CmptAnimExample(Timeline):
    def construct(self) -> None:
        circle = Circle(color=BLUE, fill_alpha=0.5)

        self.show(circle)
        self.forward()
        self.play(circle.anim.color.set(GREEN))
        self.play(circle.anim.fill.set(alpha=0.2))
        self.play(circle.anim.points.scale(2))
        self.forward()

Note

self.show(circle) displays the circle immediately, without an animation process.

Hopefully, you haven’t forgotten that the command to execute is:

janim run <file_name> <timeline_name>

If the above code is also written in learn.py, then it is:

janim run learn.py CmptAnimExample

Exporting Videos

Warning

To export videos, please make sure FFmpeg is installed and correctly added to the environment variable PATH.

The preview method mentioned above is used by:

janim run learn.py CmptAnimExample

If you want to export this animation as a video, replace run with write:

janim write learn.py CmptAnimExample

By default, the output video will be in the videos/ folder in the directory.

If you add -o, the video file will open automatically after export:

janim write learn.py CmptAnimExample -o

Real-Time Preview

If you need to close the window, modify the code, and re-execute each time you modify the animation, it would be too troublesome.

Therefore, after modifying and saving the code, you can click “Rebuild” in the “Files” menu in the top left corner of the window (shortcut is Ctrl+L), which will update the animation content to match the modified code.

It might still be a bit troublesome to manually rebuild after every modification. JAnim also provides a feature to automatically rebuild upon saving:

If you use VS Code for development, you can install the VS Code extension janim-toolbox.

When running, add -i to the preview animation command, for example:

janim run learn.py CmptAnimExample -i

After execution, the output should add a line: Interactive port has been opened at xxxxx

Tip

You might have noticed that the preview window is by default on top on the right side of the screen.

It is recommended to place VS Code on the left side of the screen, and close the sidebar for writing.

You can also change the window position or display it on another screen; see Window Position.

First, in VS Code, by default, you need to press Ctrl+J Ctrl+C (press in sequence, these are combo keys). If successful, it will show 已连接到界面端 xxxxx in the status bar in the lower right corner of VS Code.

Next, make changes to the code and save, and the preview content will be updated immediately.