How To Render Symbols
Symbols are defined by a cml symbol object. They are generated by the symboliser, from a cml conceptcode object, and they define what graphics are required to display the underlying conceptual information.
Symbols often contain more than one graphic. They will always have a "main" symbol, but may also have one or more "qualifiers". These are graphics to be displayed in a certain location next to the main symbol, in order to add to it's meaning.
Rules for Rendering Symbols and Qualifiers
As well as the "main" symbol, the following qualifers are defined:
- Top - this is to be rendered above the main symbol
- Full Left - this is to be rendered to the left of the main symbol, and should be displayed full height
- Top Left - this is to be rendered to the left of the main symbol (and full left qualifier if present), half height, aligned to the top
- Bottom Left - this is to be rendered to the left of the main symbol (and full left qualifier if present), half height, aligned to the bottom
- Full Right, Top Right, and Bottom Right - the same as their "left" counterparts, but on the right of the main symbol
The following image shows the image locations relative to the main symbol, without the top qualifier:
The full-height qualifiers should always be displayed adjacent to the main symbol, and the half-height qualifiers should be displayed outside the full-height qualifiers, if they are present.
When displaying a top qualifier, the main symbol height should be reduced by 20%, and the top qualifier should take up the rest of the vertical space, as shown in the following image:
Note that symbols do not necessarily have a square aspect ratio. You should always assume a base size for your symbols, and work out the width based on the width of the individual symbols involved.
This image shows an example of a symbol, where the images are non-square:
Note, the red box is the "main" symbol area. The top qualifer and main symbol should be centered within it (either one may be wider.)
Note that the half-height qualifiers are justified to be in contact with the main symbol, or full qualifier if present, rather than centered within their own area. (I.E. the left half-height qualifiers are aligned to the right, and vice versa)
Of course, it is highly unlikely that you will get a symbol where all of the qualifier positions are filled. The following images represent the kinds of thing you might see in practice:
Finding the Symbols to Display
Each cmap contains a list of conceptcodes, which contain information about the linguistic concept to which that cmap refers. In order to obtain symbols from a concept, you must call the conceptToSymbol operation on the symboliser.
The conceptToSymbol operation takes a list of concepts as it's input. This is so you can provide many concepts to the symboliser at once. (This is done to reduce the number of times you will have to call the web service, when rendering a long document.)
As well as this, it also takes a symboliserRenderOptions object, which allows you to choose which symbol set, colour, and symbol size you want to use. This object also contains more advanced options, to allow you to choose what types of symbol to display, and what wordlists to use.
The output of the operation is a list of symbol lists. For each concept that you supply in the input list, there is one symbols element in the output. Each symbols element may contain any number of symbol elements. It is possible that each concept may generate multiple symbols, or alternatively no symbols at all.
It is important to note that for each cmap you have, you may have more than one conceptcode, and for each conceptcode you may have more than one symbol. So, you could have three or more symbols for a single cmap.
Rendering Symbols in Practice
Further information on how to use the above information in a real-world application is available in the following sections: