DrawingText

This documentation is for a much older version of cornerstone-tools. While it may still loosely apply, more recent information can be found at https://tools.cornerstonejs.org

Tools often need to draw text on the image (e.g. the length of a measurement or the mean/stddev of a ROI). A tool that needs to draw text must first listen for the CornerstoneImageRendered-Event on the enabled-element the tool has been enabled, activated or deactivated for. When the tool's handler is called to handle the event, the canvas context used by cornerstone to render this image is passed as event data. The tool handler therefore draws text using HTML5 canvas context functions.

It is often desired to draw this text near (or attached) to the geometry in a font size that is readable regardless of the zoom/scale of the image. Drawing the text relative to the Pixel Coordinate System is made easy with the setToPixelCoordinateSystem() function, but this also causes a problem with determining which font size to use as the text size is effected by the transformation matrix applied to the canvas object. For example - drawing text with a font size of 12px will look fine when the image's scale is 1.0 but will be too large if you scale the image up past 3.0 (which frequently happens in medical imaging). You can reduce the font size based on the viewport scale but there are some issues with this:

1. Canvas does not support fractional font sizes. You can do 12px or 11px but you can't do 11.5px. This causes the text size to "jump" in annoying manner while zooming interactively.
2. You can't go below 1px font. If you highly zoom in on the image, you will be faced with either not showing the text (0px does not show up) or making it too large.
3. You have to calculate the font size based on the scale. Not hard, but something that every tool should not have to remember to do.

To address these issues, the function setToFontCoordinateSystem() was created that will modify the transformation matrix to be in Pixel Coordinate System but zoomed out to make the font size transitions more smooth. This function returns an object with the following properties:

• fontSize - the fontSize to use to display text with the same height as 15pt text on a canvas context with a scale of 1.0. You can use this when setting the font property on the canvas context.
• lineHeight - the height of a line at that font size. This is useful when you need to draw multiple lines of text as the distance between them varies depending upon the viewport scale.
• fontScale - the actual scale applied to the transformation matrix from the Pixel Coordinate System. Divide coordinates in the Pixel Coordinate System by this number to convert them to the transformation matrix applied by setToFontCoordinateSystem()

NOTE: setToFontCoordinateSystem() currently takes the desired on screen font size as a parameter, need to decide if we should remove this and always return it relative to 15px or allow the developer to specify the desired on screen size as a parameter. They could just scale the font size by 25% if they want it bigger. NOTE: Make sure you call setToPixelCoordinateSystem if you need to render geometry after you render text using setToFontCoordinateSystem TODO: Rethink the name of setToFontCoordinateSystem, there must be a better name

A common strategy for a tool would be to:

1. Call setToPixelCoordinateSystem() to set the canvas context to the Pixel Coordinate System and draw geometry.
2. Call setToFontCoordinateSystem() and draw text.