layout markup and visualization

Jeremy Douglass

Panelcode is a minimal markup language for describing visual compositions as abstract layouts.


Use Panelcode to quickly encode visual layouts for search and visual exploration. Panelcode is optimized to be quickly and easily writable, readable, and editable by hand, with an emphasis on speed, concision, and human judgement. The tools were developed with a particular focus on compositions made of panels such as those occuring in comics, graphic novels, newspapers, magazines, websites, et cetera, and the first test cases have been performed on comics.


Panelcode has multiple encoding schemes, but examples in this document use its base scheme: gridcode. Panelcode also has many extensions and shorthands, a number of which are touched on here: markup for blank spaces, annotations, unencoded regions, panel shapes, and bleeds. Finally, Panelcode has renderers to create multiple outputs, including SVG (Scalable Vector Graphics), scaffolding TEI-XML, and HTML-Tables.


This document focuses on the gridcode HTML5-CSS3 renderer, which presents panelcode as both HTML5 web content and stand-alone SVG image files. It is an illustrated tour of some of Panelcode's features. Rather than walking through the complete language syntax, or discussing the design of the parser, it instead focuses on the gridcode renderer and walks through an illustrated tour of basic examples of Panelcode and what you can do with it: describe, summarize, compare, annotate, and vizualize layouts. This renderer supports:

Basics: Rows and Columns


Panelcode is a very efficient shorthand when encoding simple page layouts. Encodings may be written by hand and then parsed and programmatically processed for many purposes: searching, analyzing, rendering graphics and creating information visualizations, or producing scaffolds for layout editing or marking up pages with metadata.

A number in Panelcode signifies a simple row of panels. A single number ("3") is a valid Panelcode string that describes a layout with a single row of 3-columns.


In Panelcode, a sequence of panels is the basic unit of description: A "4" means four panels, as in a typical daily newspaper comic, for example. Those panels proceed in whatever typical reading order they were encoded in -- left-to-right rows and top-to-bottom columns, in this case, but Panelcode input and/or output can be automatically mirrored for e.g. manga, scanlations and imported reprints.

Simple rows are then combined into a column stack to form a layout. Layouts, in turn, may be joined into multi-layout collections, like the pages of a book, or the cells in a filmstrip.


The default row operator "_" (the underscore) is the glue used to build complex pages by connecting of simple rows. While 3 described three horizontal panels, 1_1_1 describes three vertical panels. This can be made more concise with one of the shorthand extensions, but it reflects a fundamental aspect of gridcode encoding design: the primary reading order (in this case, left-to-right) commonly appears in a different way than the secondary reading order (top-to-bottom). In fact, panels connected by the column operator "+ are commonly collapsed into row counts: the horizontal panelcode layout 3 could also be writtn 1+1+1; the vertical panelcode layout 1_1_1 can (with an extension) be written 3v.


When the row operator is used to combine rows then each row may have different panel counts, and every row is assumed by default to be full-width with its own unique panel dimensions. This is fundamentally unlike a spreadsheet, HTML <table>, or other tabular data presentation system. In such systems columns are fixed, and rows must be marked of in units or multiples of those columns. In order to create a 1_2_3_4 on a spreadsheet requires 12 columns, and each row must be expressed in multiples of those columns.

These fixed column constraints are essentially the limitations of attempting to express design grids in tabular data presentation formats. By contrast Panelcode is based on a flexible design grid paradigm -- and in fact uses the emerging CSS flex / flexbox and CSS grid standards for this renderer, which are likewise based on an evolution of web design away from tabular data and towards design grids. [Although note that the original Panelcode HTML-Tables renderer accomplished this by making every row or rowgroup its own independent table -- such workarounds are often painful, but not impossible.]

This is not to say that spreadsheet-style grids are impossible or even difficult in Panelcode. A chessboard-sized grid can be described by an8_8_8_8_8_8_8_8 -- or, using multiplier shorthand, an 8x8.

Reading a Panelcode Image

Panelcode visualizations may have a different appearance and different elements depending on the renderer, however there are some basics that are common to the Panelcode concepts. Consider this glyph:

A Panelcode glyph is an abstract representation of a layout -- like a design wireframe. It may describe a page, a screen, or some other medium -- and, in fact, it may describe many different objects as having the same abstract composition. In fact, this abstraction is the key to comparing disperate layouts. (To say that two graphic novel pages have the same glyph is less like saying two songs have the same notes or two poems have the same rhymes, and more like saying two songs have the same rhythm, or that two poems have the same rhyme scheme.)

The margins of a Panelcode glyph may display additional information, including:

Depending on the renderer this box-model of a page or screen may support empty area and unencoded regions (see more below). It may also support the use of encoded metadata to styling panels with different textures or colors etc. to indicate their nature -- e.g. full page spread -- or annotations of contents -- e.g. incidents of speech (see more below). Panelcode glyphs are designed to be viewed en masse in large collections or from a distance, but individaul panels may include numbers that indicate the encoding order -- which is often (but not always) the expected reading order for the panels in a given layout.

Panelcode glyphs appear by default on an abstract unit square -- for example, it is neither the vertical rectangle of the comic book nor the horizontal rectangle of the newspaper cartoon strip. This is to emphasize the concept that a particular geometric arragement of panels might refer to either medium, or both, or something.Panelcode glphys can also be styled to media-specific dimensions -- either the dimensions of a media genre (e.g. a contemporary US comic), a specific object (e.g. Mouse Guard), or a mixed media collection (e.g. the artifacts of Building Stories).


Spans are a simple way of creating more complex layouts than combining rows will allow. A span specifies that a panel is proportionately wider that other in its row (column span) or that a panel occupies multiple rows in a rowgroup (row span). A panel may have both its column span and row span specified. In Panelcode spans are indicated with the c and r attributes, which are attached to panels as suffixes.

A row with one column twice as wide as the other may be written 1+c2. Why? Follow these steps:

			  1:    2
			  2:    2(1 + 1   )
			  3:    2(1 + 1.c2)
			  4:    2(1 + c2  )
			  5:     (1 + c2  )
			  6:      1 + c2

The panelcode 2 is expanded into a group (1+1) of individual panels. One of those panels is annotated with the suffic .c2 -- this sets the column span equal to 2, making the second column twice as wide as the first (and its default of 1). The result is 2(1+1.c2)

We can additionally note that almost all of this is optional. A columnspan modifies a single panel by default, so 1.c2 may simply be written c2. The 2( outside the group is hint at the contents, but it is also optional -- and there is only one group, so the group markers are also optional. The concise result? 1+c2.

For rows that cross cross vertically into multiple rows, a special rowspan indicator is used with "r" for row plus the number of rows to span ("r2", "r3").

This concept of a "rowspan" argument is present in early HTML-Tables, and also incorporated into CSS-Grid. Panelcode uses these concepts in part because they are longstanding traditions in rendering tabular data, and in part because shared concepts make it easier to parse a panecode string into a straightforward sequence of HTML or CSS elements that can directly render the described layout.

Compare with these very similar panel groups. Because the long panel is oriented horizontally rather than vertically these layouts can be described with a long row ("1"), and the encoding does not require rowspan notation. In fact, these do not require special column notation either -- a full-row panel is simply "1".

Column spans and row spans may also be combined, as in the multi-row, multi-column panel in this example:

Display sizes and styles

Panelcode can be rendered in different display sizes and styles for different purposes. Shown here: full size (default), thumb, mini, micro, and micro2.

These glyphs are the same html or SVG output, but rendered with a different CSS3 class label. The level of display detail is styled as well -- "thumb" has a caption and panel id, "mini" has only a caption, and "micro" is just a bare glyph image. Collections of Panelcode glyphs can be restyled at the gallery webpage level by changing a single class tag.


Sequences and Sorting

The following sequence counts through the number of simple, row-based compositions of 1-3 rows, and 1-3 panels per row, giving a maximum grid of 3x3.

An interesting property of Panelcode strings is that, once reduced to simple rows, each string is part of a numeric sequence, counting through the space from a blank page up to the maximum compositional grid. For example, given a work which is never more than 3 columns wide or 3 rows tall, any Panelcode is a ternary number (base 3), running from 1 (a full page) to 3_3_3 (a 3x3 grid).

Panelcodes (and hence the layouts the represent) can be sorted ), and these sortings have some interesting properties. and a set of strings can be sorted. This sorts a . ternary (base 3) number. complexity of each page. A zero-padded numeric sort (shown here) (those composed of simple rows) is that they can be sorted within a maximum grid (e.g. 2x2, 3x3, 4x4). Different sortings methods present different groupings of intuitively "similar" layouts. For example, an alphabetic sort groups layouts by increasing complexity of the top row (1, 2, 3 panels) and then by the second row within each group (1_1, 1_2, 1_3), et cetera.


Consider the example of comics. While some genres of comics (such as newspaper strips) generally subdivide the available space into panels, many other forms commonly use compositions that leave significant regions of blank space.

When a 0 is used to encode a blank region the corresponding empty area is rendered on the Panelcode grid. For example, 1_0 encodes a page whose bottom half is empty.

In the most complex cases, empty panels can also take column and row arguments, so compositions with large whitespace regions or complex combinations of blank and filled areas can be quickly marked: (0+0c2r2,1)_(c2+0)_(1+c2).

Complexity and ambiguity

An empty or blank panel is a placeholder -- the 0 in a blank panel indicates that it does not count towards the total of a group or a total composition. By contrast, unencoded regions may count more.

An unencoded region is a collection of panel-like objects whose geometry is too complex or too non-cartesian to be encode in Panelcode shorthand.

Shape annotations

Scale is a descriptions independent of the encoding direction. Whether using left-to-right (LTR) or right-to-left (RTL) encoding, a scaled panel will look the same.

This is not the case for skew, tilt, or rotation, however. These are described in terms of the reading / encoding order. Skewing "forward" leans in to the reading direction, "back" leans away. Tilting and rotate "up" rises in the reading direction, "down" falls.

Color Styles (panel marking)

Color may also be used to mark layouts or panelgroups, in which case the color appears in the gutters. For example, black-filled pages and gutters are often used to indicate flashbacks.

Annotations may mix the styles. For example, black gutters, or a blacked-out panel, or both.

Comic Books

Newspaper comicstrips: ratios and flow

The newspaper comic strip, as a form, has a very interesting relationship to panel geometry. Panels almost invariably hhave a fixed height and often have a fixed sequence of width ratios -- traditionally 3:1:2:2:1:3. These ratios were designed with a fluid layout property: a single piece is produced as a six-panel sequence may be laid out (or may have been laid out) in a variety of column counts and aspect ratios in different newspapers, taking up a quarter page or half page, respectively -- or a third of a page, if the optional first two panels are dropped -- or even (rarely) a full page.

When there is no specific page (or there are many pages, or the page is fluid) then Panelcode can render a sequence of panel geometry without a particular page formatting.

(NOTE: did this with w12, could create wx and/or use flex. Also overrode unit square dimensions manually-- could make horizontal scroll a style tmeplate).

The Panelcode here is a simple list of column ratios. It has been further annotated with color so that we can more easily see the panels flow between different layouts.

	(1.c3     + 1        + 1.c2       + 1.c2      + 1      + 1.c3)
	( + 1.yellow + + 1.c2.cyan + + 1.c3.magenta)

While a comic strip would never appear in this extreme horizontal format in a newspaper, this stream of panels can automatically flow into a dynamic layout -- for example with no particular columns specified, the CSS3 layout algorithm packs the panels into a unit square like this:

Not coincidentally, the CSS3 Grid layout algorithm has here recreated the "Sunday full-page," one of the layouts for which the six-panel comic strip format was originally designed. Other major reconfigurations of the Sunday newspaper also emerge automatically from setting the number of layout columns, including the quarter-page, half-page, and full-page.

One of the interesting properties of Panelcode is that these simple layout regroupings -- the kind that a newspaper might perform during layout -- are manifest in the transformation of one layout to another. Beginning with the Panelcode for a long strip of panels, we can indicate the row groups of any of the standard newspaper layouts merely by rearranging parantheses:

	no col, 1 rows:  (c3 + 1 + c2 + c2 + 1 + c3)
	 6 col, 2 rows:  (c3 + 1 + c2)_(c2 + 1 + c3)
	 4 col, 3 rows:  (c3 + 1)_(c2 + c2)_(1 + c3)
	 3 col, 4 rows:  (c3)_(1 + c2)_(c2 + 1)_(c3)

While in graphic novels and comicbooks the unit of composition is often the page itself, in the comicstrip the unit of composition is often part of a page -- whether in a newspaper publication or in a compendium of reprints. Panelcode can be used to mark up compositions of multiple layouts, layouts can be joined together into pages, and pages can be joined together into two-page spreads (or more).

Daily strips might be in a single column or in a double-column -- e.g. see THE DAILY GRUNT, 2003 or a 1949 comics page from the Huntingdon Daily News. See also a Daily Herald Sunday page.

Direction: LTR and RTL

An encoding may indicate and be rendered in LTR or RTL reading order.

Here the same Panelcode string is rendered in Japenese manga reading order on the right and as a mirrored translation on the left. Panel labels are preserved, with "1" starting in the upper right or upper left, respectively.

A sequence of pages can also be rendered RTL, as when encoding the pages of a tankoban. Here the Panelcode: rendered as a right-to-left page sequence of RTL pages, with panel "1" beginning on the far right and "9" ending on the lower left.

Bleeds [experimental]

Bleeds are an annotation on a panel indicating that it proceed to some edge(s) of the space. A panel may bleed to one edge, two edges, three edges, or four.

Half-Page Bleeds

Half page bleeds are a work in progress. They should look like the last example -- and be indicated by encoding the panel with its three bleed edges (down, left, right). There are a lot of display problems, however, and in practice a simple directional bleed (down) is currently a more reliable approximation.

A minor issue: bleeds on the right side in a 2-unit spread may cross the centerline.

Some issues with needing to be in a spread div otherwise the left edge loses containment. Some magic numbers in the css to manage offsets that go along with the scaling.

The label div needs to come after bleed panels in order to be above them (visible) -- could try controlling with z-height.