Welcome to the Drawlib Documentation!
Drawlib is a pure Python drawing library crafted to facilitate Illustration as Code rather than focusing solely on creating polished illustrations. Witness Python code in action generating a circular image:
Code makes Illustration
As you can see, we define circle location, size and styles at left side code. Executing it generate right side circle image. You will get illustration as you code.
Various Drawing Items
Drawlib offers a variety of drawing items with different styles. Below is a sample image showcasing the major drawing items with varying styles.
Various drawing methods
Icon: Over 1500 patterns available in 5 styles (thin, light, regular, bold, fill)
Image: Easily apply effects
Line: Supports many styles
Shape: Around 20 patterns
Text: Various sizes, fonts, and weights (light, regular, bold), supporting major local languages
Drawlib is inspired by the features of Microsoft PowerPoint. We aim to implement as many popular features as possible. In addition to basic drawing features, Drawlib includes advanced features such as a code highlighter, implemented as smart art.
Concept: Apply Style to Content
The parameters of a circle include coordinates, size, color, etc. Many drawing tools treat these parameters uniformly. However, we divide them into two parts:
Content: The type of drawing items, such as coordinates, size, angle, etc.
Style: Elements like color, line width, and font.
If you are familiar with HTML/CSS, content is analogous to HTML, and style is analogous to CSS. Just as it’s recommended to define styles in CSS and reference them in HTML, Drawlib encourages defining styles separately and referencing them in the illustration code.
Apply style to content
From an artistic perspective, the mix of content and style is essential. However, for illustrations that do not require an artistic look, the content is more critical than the styles. The color or width of a line is less important than where the line is drawn.
Separating content and style allows you to focus on the essential content first. Once the content is created, you can modify its appearance by changing styles outside of the content. Additionally, you can apply one style to many content items if they are separated. Using the same style for many items is crucial for achieving consistency in illustrations.
How Style Works
In the first example code, we define the style ShapeStyle for the drawing item circle().
This approach is straightforward, but repeating styling for each item can be burdensome and may lead to inconsistencies.
Instead, we typically use themes and their styles to change the drawing item styles consistently.
Drawlib’s style system is similar to CSS. You define the style in one location and reference it everywhere. The style is then automatically applied to the items. This means you don’t need to provide detailed styles for each drawing item.
Here is a style code similar to CSS. This code itself doesn’t generate any illustration but contains the style definitions.
1from drawlib.apis import *
2
3# Define ShapeStyle with name "mystyle"
4dtheme.shapestyles.set(
5 style=ShapeStyle(
6 lstyle="dashed",
7 lcolor=Colors140.BlueViolet,
8 lwidth=3,
9 fcolor=Colors140.Turquoise,
10 ),
11 name="mystyle",
12)
13
14# Define TextStyle with name "mystyle"
15dtheme.textstyles.set(
16 style=TextStyle(
17 color=Colors140.BlueViolet,
18 font=FontSansSerif.RALEWAYS_REGULAR,
19 size=32,
20 ),
21 name="mystyle",
22)
And here is an illustration code similar to HTML. It imports the style you defined earlier. When importing it, the style definitions are automatically loaded.
1from drawlib.apis import *
2
3# Import styles like HTML reference CSS
4import docs.style
5
6# Configure drawing canvas size
7config(width=100, height=50)
8
9# Apply predefined styles
10circle(xy=(25, 30), radius=10, style="mystyle")
11text(xy=(25, 10), text="Circle", style="mystyle")
12rectangle(xy=(75, 30), width=20, height=20, style="mystyle")
13text(xy=(75, 10), text="Rectangle", style="mystyle")
14
15# Save canvas
16save()
Executing the illustration code generates this image. As you can see, the pre-defined styles are applied correctly.
Illustration code references style code
You can define your own styles like this. However, we recommend using themes rather than creating your own styles. Themes come with many colors and predefined popular styles. If you don’t require very fancy styles, the theme styles might be sufficient. Please take a look at the quick-start documentation first.
Good to build lots of images
In contemporary software development, version control extends beyond code to encompass documentation, all managed seamlessly through Git. While I compose technical documents and literature using VSCode and Markdown, I previously relied on PowerPoint for illustrations. However, this approach lacks compatibility with versioning documentation images.
Enter Drawlib, a solution meticulously developed to address this issue. With Drawlib, not only can textual documentation be version-controlled, but illustration code can also be managed through Git. This facilitates the automation of build tasks via scripting or CI/CD pipelines.
Doc image/text build flow.
Integrating Drawlib into your workflow is straightforward and doesn’t significantly differ from managing markdown documents. If you create your documentation using markdown or a similar format, you can easily adopt drawlib.
Incidentally, the image above is created using Drawlib, serving as a practical example of Drawlib’s capabilities. We generate hundreds of such images from image codes with consistent styles for writing books.
Refer to the Quickstart guide for a comprehensive understanding of Drawlib’s underlying concepts. Almost all images within this documentation are generated using Drawlib. Exceptions include only screenshots and original image files such as the Python logo. Even the source code image in the first example is generated by Drawlib using its smart art feature.
Introductions:
Foundations:
Advanced Topics:
Smart Arts: