Shodo :: Drawing Text in a <canvas>

Shodo is a Javascript package used to render text within <canvas> elements from font images generated by the Suzuri library.

Downloads:
What is Shodo ? How do I use Shodo ? Details Usage Docs Where can I get more fonts ? What about IE ? What does Shodo text look like ? Who is using Shodo ? What are Shodo's license terms ? Who can I contact for help and more info ?
Packed Shodo Javascript package (includes modified excanvas.js, and json2.js) Suzuri Perl package (includes Shodo Javascript libraries) Suzuri Windows executable

What is Shodo ?

Formally, shodo is Japanese calligraphy. "shodo" is roughly translated as "art of writing". Practitioners of the art are known as "shodoka".

Currently, the HTML <canvas> tag does not provide any means of drawing text, and, as of this writing, HTML5 has not added the capability. This ommission has proven a challenge to developing rich <canvas> based applications.

A number of solutions have been developed to provide text support for <canvas>, including

layered DIVs: can be difficult to properly align over the canvas.
direct vector rendering: compute intensive for the Javascript environment
image slicing: requires pre-generation of a font image, with metric/position mapping data

Shodo applies the image slicing solution, using the Suzuri utility to generate the font images. While image slicing is less flexible than the other 2 approaches, it may be more precise than layered DIVs (due to directly embedding the font images in the canvas), and less compute intensive than the direct rendering solution. In addition, image slicing permits the use of fonts not resident on the browser's platform, and the ability to rotate the strings to arbitrary angles.

How do I use Shodo ?

The process is straightforward:

Using Suzuri, generate a font image and associated JSON metric/position data for the desired font family, size, slant, weight, color, and opacity (or you may choose to download a prebuilt font from the Shodo font catalog).
Load the Shodo package in the <head> of the webpage
As you build your canvas content, create a font foundry via
```
	var shodo = Shodo.Foundry(canvasctxt, fontjson);
```
Only a single foundry is required for a given canvas; however, each canvas must have its own foundry object.

If desired, additional fonts can be added to the foundry after it is created:

	var fontlist = shodo.addFontsFromJSON(fonts_as_json, function { });
	//
	//	rarely used, primarily called from the other 2 methods
	//
	var fontobj = shodo.addFont("arial", 16, "green", 1.0,
		"abcdefghijklmnopqrstuvwxyz", positions, widths, 18, "http://some.domain.com/charset.gif",
		function {});
	var otherfont = shodo.addNamedFont("arial_bold_20_black", fontdesc,
		"abcdefghijklmnopqrstuvwxyz", positions, widths, 18, "http://some.domain.com/charset.gif",
		function {});

For each font to be used within the canvas, use the foundry object to create a font object:

	var arial_10_black = shodo.getFont("arial", 10, "black");
	var georgia_16_red_50 = shodo.getFontByName("georgia_16_red_50");
	...

To draw a string, use a font object:

	// draw string from (40,120) with a 3 pixel linespacing, right aligned,
	// at a 45 degree angle
	//
	arial_10_black.drawString("This is a string", 40, 120, 3, "right", 45);
	//
	//	draw a string aligned to (100,100) at a 90 degree angle
	//
	georgia_16_red_50.drawAlignedTo("An aligned string", 100, 100, 3, 90);
	//
	//	draw string centered above a point, offset by 5 pixels
	//
	arial_10_black.drawAbove("This is on top", 300, 240, 5);
	//
	//	draw string centered below a point, offset by 5 pixels
	//
	arial_10_black.drawBelow("This is underneath", 300, 240, 5);
	//
	//	draw string centered to the left of a point, offset by 3 pixels
	//
	arial_10_black.drawLeftOf("This is on top", 300, 240, 3);
	//
	//	draw string centered to the right of a point, offset by 3 pixels
	//
	arial_10_black.drawRightOf("This is on top", 300, 240, 3);

To dynamically load a new font, use the JSON produced by Suzuri (retrieved via, e.g., an XMLHttpRequest):
```
	var newfontname = shodo.addFontFromJSON(newfont);
```

Refer to the Shodo JSDoc for detailed interface descriptions.

Note that, at this time, Shodo does not provide a method to follow text around a non-linear path.

Where can I get more fonts ?

I recommend the Cooltext website, which hosts over 1200 freely available fonts (check each font for its conditions of use) in TrueType format (as well as hosting a great logo/button rendering service).

After downloading fonts from Cooltext, you can install them in Windows by

Open Start->Run...
Enter "%windir%\fonts"
In the font explorer, select File->Install New Font
Select each font file from the Explorer and click Open; the font will then be installed.

A small catalog of fonts is also available for you to download and play with.

What About Internet Explorer ?

IE does not implement the <canvas> element; however, Shodo supports the excanvas VML-to-canvas adapter library for Microsoft® Internet Explorer (versions 6 and 7).

Internet Explorer 6 VML Security Note

In late 2006, a VML security exploit was discovered in IE6. At that time, many users disabled VML in their browsers. Since that time, a patch has been provided (both standalone, and as part of the general patch updates) to correct that vulnerability. If you do not see the text rendered by Shodo, you may need to re-enable VML using this command from a Command Prompt:

regsvr32 "%ProgramFiles%\Common Files\Microsoft Shared\VGX\vgx.dll

To later disable VML:

regsvr32 -u "%ProgramFiles%\Common Files\Microsoft Shared\VGX\vgx.dll

If you still do not see the rendered text, and your system is part of an internal network, your IT department may have disabled VML support through Active Directory. In that case, your only options are

convince your IT department to re-enable VML support
switch to a better browser

Where possible, we recommend the latter solution, as it will also improve the text rendering performance. The most recent releases of Opera perform particularly well; Firefox 2 or the recent beta release of Apple Safari also perform very well.

What does Shodo text look like ?

See for yourself! The Shodo sample page provides several fonts with which you can experiment.

Who is using Shodo ?

Shodo is used by PlotJax to render text in <canvas> based charts/graphs.

What are Shodo's license terms ?

Shodo and Suzuri are freely available to use, copy, modify, and redistribute under the terms of the Apache License 2.0.

The Suzuri executable includes components with alternate, but compatible licenses:

The following are licensed under the Perl Artistic License:

The following is licensed under the MIT License:

giflib

Who can I contact for help and more info ?

Send help requests, suggestions, and bug reports to shodo@presicient.com. If there is sufficient interest, I may startup a mailling list or wiki.