Skip to content

Proofread -annotate section #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 22, 2025
Merged

Proofread -annotate section #12

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6881c5f
Proofread -annotate section
JohnVeness Jun 12, 2025
f18aacb
Fix "an"
JohnVeness Jun 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions text/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1851,7 +1851,7 @@ <h3>Bounding Box Overflow</h3>One of the biggest problems you will probably come
</tr>
</table><!-- ------ -->
<a name="annotate" id="annotate"></a>
<h2>Annotate - Text Drawing Operator</h2>With IM version 6, a new font drawing operator, "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>", was made available. This operator is in may ways much simpler that using a "<code><a href="https://imagemagick.org/script/command-line-options.php?#draw">-draw</a></code> text" operation, but as it uses the '<code>annotate()</code>' API (Application Program Interface), it is also more powerful. While the operator does make use of the "<code><a href="https://imagemagick.org/script/command-line-options.php?#draw">-draw</a></code>" primitives, it does so in a more complex way, such as expanding special <a href="#escape_chars">escape characters</a> to add extra image information and even multiple lines, and applying a coordinate system transform to the drawn text to produce slants and rotations. Because of this, the operator is now the preferred text drawing operator for all ImageMagick text drawing and image annotation, and this is now reflected in these example pages. Here is a basic example using this operator.
<h2>Annotate - Text Drawing Operator</h2>With IM version 6, a new font drawing operator, "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>", was made available. This operator is in many ways much simpler than using a "<code><a href="https://imagemagick.org/script/command-line-options.php?#draw">-draw</a></code> text" operation, but as it uses the '<code>annotate()</code>' API (Application Program Interface), it is also more powerful. While the operator does make use of the "<code><a href="https://imagemagick.org/script/command-line-options.php?#draw">-draw</a></code>" primitives, it does so in a more complex way, such as expanding special <a href="#escape_chars">escape characters</a> to add extra image information and even multiple lines, and applying a coordinate system transform to the drawn text to produce slants and rotations. Because of this, the operator is now the preferred text drawing operator for all ImageMagick text drawing and image annotation, and this is now reflected in these example pages. Here is a basic example using this operator.
<div align="center">
<table class="table table-sm table-hover table-striped" cellspacing="0" cellpadding="5" width="90%" bgcolor="#F8F8F8">
<tr>
Expand All @@ -1863,7 +1863,7 @@ <h2>Annotate - Text Drawing Operator</h2>With IM version 6, a new font drawing o
</td>
</tr>
</table><a href="annotate.gif"><img src="annotate.gif" width="320" height="100" align="middle" vspace="5" hspace="5" border="1" alt="[IM Output]"></a>
</div>One of the extra features of the "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" operator is that it can rotate the X and Y axis of the drawn text completely separately to each other. This is done by providing the angle in which to rotate each axis as a 'image size' in the operators argument. Just to show how complex a single "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" operation can be, here is a boxed, stroked, and slanted image...
</div>One of the extra features of the "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" operator is that it can rotate the X and Y axis of the drawn text completely separately to each other. This is done by providing the angle in which to rotate each axis as a 'image size' in the operator's argument. Just to show how complex a single "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" operation can be, here is a boxed, stroked, and slanted image...
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you also change a 'image size' to an 'image size'?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, done :)

<div align="center">
<table class="table table-sm table-hover table-striped" cellspacing="0" cellpadding="5" width="90%" bgcolor="#F8F8F8">
<tr>
Expand All @@ -1876,7 +1876,7 @@ <h2>Annotate - Text Drawing Operator</h2>With IM version 6, a new font drawing o
</td>
</tr>
</table><a href="annotate_opts.gif"><img src="annotate_opts.gif" width="320" height="100" align="middle" vspace="5" hspace="5" border="1" alt="[IM Output]"></a>
</div>In this example all four annotate arguments are given. Specifically, X axis rotation, Y axis rotation, and the fonts X and Y position on the background image. Also note that the fill pattern (set with "<code><a href="https://imagemagick.org/script/command-line-options.php?#tile">-tile</a></code>") is also slanted with the font. That is, because it is drawn using a sheared/rotated coordinate system, which also shears and fill pattern tiled within the drawn text. Further example of this shearing capability is the <a href="../fonts/#slewed">Sheared Shadow Font</a> example. Compare that with the <a href="../fonts/#slanted">Slanted Font</a> created with the equivalent "<code><a href="https://imagemagick.org/script/command-line-options.php?#draw">-draw</a></code>" MVG string. For a table summarizing the effects of the "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" shearing operation, see <a href="../misc/#annotate">Annotate Argument Usage</a>. For example, here is some slightly rotated text ...
</div>In this example all four annotate arguments are given: X axis rotation, Y axis rotation, and the font's X and Y position on the background image. Also note that the fill pattern (set with "<code><a href="https://imagemagick.org/script/command-line-options.php?#tile">-tile</a></code>") is also slanted with the font. That is, because it is drawn using a sheared/rotated coordinate system, which also shears the fill pattern tiled within the drawn text. A further example of this shearing capability is the <a href="../fonts/#slewed">Sheared Shadow Font</a> example. Compare that with the <a href="../fonts/#slanted">Slanted Font</a> created with the equivalent "<code><a href="https://imagemagick.org/script/command-line-options.php?#draw">-draw</a></code>" MVG string. For a table summarizing the effects of the "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" shearing operation, see <a href="../misc/#annotate">Annotate Argument Usage</a>. For example, here is some slightly rotated text...
<div align="center">
<table class="table table-sm table-hover table-striped" cellspacing="0" cellpadding="5" width="90%" bgcolor="#F8F8F8">
<tr>
Expand Down Expand Up @@ -1918,7 +1918,7 @@ <h2>Annotate - Text Drawing Operator</h2>With IM version 6, a new font drawing o
<a href="annotated_labels.jpg"><img src="annotated_labels.jpg" width="100" height="60" align="middle" vspace="0" hspace="2" border="1" alt="[IM Output]"></a>
</td>
</tr>
</table>You can also add other information about the current image to the Annotated string using escape characters. For example lets overwrite the built-in "<code>rose:</code>" image with information about the images size. To center the text on the image we use a "<code><a href="https://imagemagick.org/script/command-line-options.php?#gravity">-gravity</a></code>" setting, and turn off any and all rotations and offsets by using an "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" argument of '<code>0</code>'.
</table>You can also add other information about the current image to the Annotated string using escape characters. For example, let's overwrite the built-in "<code>rose:</code>" image with information about the image's size. To center the text on the image we use a "<code><a href="https://imagemagick.org/script/command-line-options.php?#gravity">-gravity</a></code>" setting, and turn off any and all rotations and offsets by using an "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" argument of '<code>0</code>'.
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td width="100%" align="justify">
Expand Down Expand Up @@ -1982,7 +1982,7 @@ <h3>Automatically Sized Annotated Text Canvases</h3>Often you need much more con
<table border="0" cellspacing="0" cellpadding="0" width="90%" align="center">
<tr valign="top">
<td><img src="../img_www/reminder.gif" width="20" height="16"><img src="../img_www/space.gif" width="20" height="16"></td>
<td align="justify" width="100%"><font size="-1"><i>Note that position of the text in a centered "<code><a href="#label">label:</a></code>" image may not exactly match the position of a centered "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" operation. The two methods follow completely different processing algorithms, and as such may not match. Especially when unusual fonts are involved.</i></font></td>
<td align="justify" width="100%"><font size="-1"><i>Note that position of the text in a centered "<code><a href="#label">label:</a></code>" image may not exactly match the position of a centered "<code><a href="https://imagemagick.org/script/command-line-options.php?#annotate">-annotate</a></code>" operation. The two methods follow completely different processing algorithms, and as such may not match, especially when unusual fonts are involved.</i></font></td>
</tr>
</table><a name="autosize_box" id="autosize_box"></a>
<h3>Auto Sized using 'Undercolor Box'</h3>Rather than using a "<code><a href="#label">label:</a></code>" image, you can draw the font on a large canvas using an <a href="#undercolor">Undercolor Box</a> and a <a href="../draw/#stroke">large stroke width</a>, before trimming the canvas to fit. For example
Expand All @@ -1999,8 +1999,8 @@ <h3>Auto Sized using 'Undercolor Box'</h3>Rather than using a "<code><a href="#l
</td>
</tr>
</table><a href="invitation_box.jpg"><img src="invitation_box.jpg" align="middle" vspace="5" hspace="5" border="1" alt="[IM Output]"></a>
</div>The amount of space around the font can be adjusted using the "<code><a href="https://imagemagick.org/script/command-line-options.php?#strokewidth">-strokewidth</a></code>" setting. The only important requirement is that the initial canvas be a color different to the background color, ('<code>lightblue</code>' in this case) and is larger than the final result. Just a word of warning, some fonts draw characters well outside the individual character drawing area. (For example see <a href="#undercolor">Undercolor Box</a> above). In this case the above result will work, but may require you to use a transparent canvas, and then overlay the result over white (using an operation like "<code>-background white -flatten</code>" for example), to magick the unused and still transparent areas to white. However that character will likely be touching an edge of the resulting image. Basically you can't really win, in all situations, just try your best. <a name="coloring_text" id="coloring_text"></a>
<h3>Coloring a Gray-scale Text Image</h3>I purposefully generated the above image as a grey-scale black and white image, as this can be used as a masking template. From a pure image like this you can then color the background and the foreground of image either separately or both at the same time. Here for example I use the <a href="../color_mods/#level-colors">Level by Colors Operator</a>, "<code><a href="https://imagemagick.org/script/command-line-options.php?#level-color">+level-color</a></code>", to globally modify the image colors so as to assign the foreground and background colors with specific values.
</div>The amount of space around the font can be adjusted using the "<code><a href="https://imagemagick.org/script/command-line-options.php?#strokewidth">-strokewidth</a></code>" setting. The only important requirement is that the initial canvas be a different color to the background color, ('<code>lightblue</code>' in this case) and is larger than the final result. Just a word of warning, some fonts draw characters well outside the individual character drawing area. (For example see <a href="#undercolor">Undercolor Box</a> above). In this case the above result will work, but may require you to use a transparent canvas, and then overlay the result over white (using an operation like "<code>-background white -flatten</code>" for example), to magick the unused and still transparent areas to white. However that character will likely be touching an edge of the resulting image. Basically you can't really win in all situations, so just try your best. <a name="coloring_text" id="coloring_text"></a>
<h3>Coloring a Gray-scale Text Image</h3>I purposefully generated the above image as a gray-scale black and white image, as this can be used as a masking template. From a pure image like this you can then color the background and the foreground of the image either separately or both at the same time. Here for example I use the <a href="../color_mods/#level-colors">Level by Colors Operator</a>, "<code><a href="https://imagemagick.org/script/command-line-options.php?#level-color">+level-color</a></code>", to globally modify the image colors so as to assign the foreground and background colors with specific values.
<div align="center">
<table class="table table-sm table-hover table-striped" cellspacing="0" cellpadding="5" width="90%" bgcolor="#F8F8F8">
<tr>
Expand All @@ -2012,7 +2012,7 @@ <h3>Coloring a Gray-scale Text Image</h3>I purposefully generated the above imag
</td>
</tr>
</table><a href="invitation_colored.jpg"><img src="invitation_colored.jpg" align="middle" vspace="5" hspace="5" border="1" alt="[IM Output]"></a>
</div>For example, here I use <a href="../compose/#mask">Composite Masking</a> to replace background and foreground with pattern images.
</div>For example, here I use <a href="../compose/#mask">Composite Masking</a> to replace the background and foreground with pattern images.
<div align="center">
<table class="table table-sm table-hover table-striped" cellspacing="0" cellpadding="5" width="90%" bgcolor="#F8F8F8">
<tr>
Expand All @@ -2028,7 +2028,7 @@ <h3>Coloring a Gray-scale Text Image</h3>I purposefully generated the above imag
</td>
</tr>
</table><a href="invitation_rose.jpg"><img src="invitation_rose.jpg" align="middle" vspace="5" hspace="5" border="1" alt="[IM Output]"></a>
</div>The <a href="../basics/#reverse">Reverse Operator</a> in the above is used to reorder the images, so the first image becomes the third 'masking' image of the composition. The foreground ("<code>plasma:</code>") image then becomes first, and the background in the middle. For other techniques of coloring a gray-scale image like this, see <a href="../compose/#mask">Using a Mask to Limit the Composed Area</a>. And more generally <a href="../masking/#masks">Using Masks with Images</a>. For other methods of generating gradients for tiling see <a href="../canvas/#gradient">Gradients of Color</a>, <a href="../canvas/#sparse-color">Sparse Points of Color</a>, and <a href="../canvas/#plasma">Randomized Canvases</a>.
</div>The <a href="../basics/#reverse">Reverse Operator</a> in the above is used to reorder the images, so the first image becomes the third 'masking' image of the composition. The foreground ("<code>plasma:</code>") image then becomes first, and the background in the middle. For other techniques of coloring a gray-scale image like this, see <a href="../compose/#mask">Using a Mask to Limit the Composed Area</a>. More generally see <a href="../masking/#masks">Using Masks with Images</a>. For other methods of generating gradients for tiling see <a href="../canvas/#gradient">Gradients of Color</a>, <a href="../canvas/#sparse-color">Sparse Points of Color</a>, and <a href="../canvas/#plasma">Randomized Canvases</a>.
<hr>
<!-- ---------------------------------------------------------------- -->
<a name="font" id="font"></a>
Expand Down