---
text
Define shapes based upon true type fonts and a string
Parameters, associated elements and modifiers must be within braces.
text {...}
The text definition is assignable to a scene language ID.
#declare ID00 = text {...}
#local ID00 = text {...}
Identifiers (IDs) may be referenced within blocks: object{}, looks_like{},
projected_through{}, bounded_by{} and clipped_by{}. IDs may also be used as
objects in the *_object collection of patterns.
Note. Normally one would expect to be able to use a text identifier within a
text{} block - and one still can, but it is strongly discouraged. The text{}
object creates a union{} or merge{} of text{} objects internally. A text{}
wrap of such IDs is incorrect, but usually works.
As of release R19 of the yuqk fork, the debug compile will flag text{ TextID }
syntax as a parse time error because the TextID has is not of type 'text{}'.
The yuqk debug compile - as a trial - has added identifier type checking via
specific wrapping block types for some object types, including text{}.
For example, when running the yuqk debug compile:
#declare Light00 = light_source ...
...
light_source { Light00 }
sphere { Light00 } // <-- Will die for a parse error here. Normally the
// parser would simply create a second copy of the
// Light00 light_source{}...
Raw text{} definitions may be used within blocks: object{}, looks_like{},
projected_through{}, bounded_by{}, clipped_by{}, difference{}, intersection{},
merge{} and union{}. The raw / immediate text{} definitions may also be used
as objects in the *_object{} pattern collection.
Options:
--------
The syntax is:
text {
ttf "fontname.ttf" "String_of_Text"
Thickness, <3D offset vector>
[merge | (merge on | off)]
[caps | (caps on | caps off)]
[open | (open on | open off)]
[OBJECT_MODIFIERS...]
}
--- Font type
The 'ttf' string must always be specified and it is currently the only font
format option. This true even where the file name is a true type collection and
has the .tto suffix. Note. Other .tto files which are, for example, open type
font collections are not supported.
--- Font filename
The '"fontname.ttf"' string is the font filename. It can be a string ID, or
function returning a string. Arrays and dictionaries may wrap the string
representation. Where the filename is not fully specified - including the
directory path to the file, POV-Ray (yuqk) will search the current POV-Ray
library paths.
Note. In the yuqk fork NO fonts are inbuilt. This reversion to pre v3.7 behavior
was taken to make the compiled executables and core install very small.
--- Extrusion thickness
The 'Thickness' value is usually >0 and it specifies the extrusion depth in the
positive z direction. It, however, can be 0.0 or negative.
When zero, a single, 2D, top surface is returned. The normal for that 2D
surface is as if the thickness was positive, but only the top, cap surface is
returned.
Where the thickness is negative, the extrusion is in the 0 to -z direction and
the normal direction for the caps is the opposite that for positive thickness
extrusion.
--- Offsets character to character in x,y and z
The '<3D offset vector>' vector is often specified as 0 or <0,0,0>. At zero it
does nothing.
It can add a little space in x between characters, say by using <0.1,0,0>. The
more essential feature is tiny offsets in z (and sometimes y) are needed to
avoid coincident surfaces where adjacent characters in a font have portions
which overlap.
With mono fonts (set pitch fonts), the vector can be used to place characters
vertically or right to left from the default. See examples below.
--- Having text{} create a union{} or merge{} of single characters
The text implementation has long, created a union{} of individual text{}
objects from each character in the passed text string. The yuqk fork has added
the option to create a merge{} of the individual text{} objects. The internal
merge{} is created by specifying:
merge
or
merge on
Using:
merge off
creates again a union{} and is equivalent to not specifying a merge setting at
all.
Note. The keyword 'merge' must follow the offset vector specification.
The merge capability is necessary any time the font has adjacent characters
which overlap and the texture is partly transparent. Otherwise the internal
surfaces often cause unwanted artefacts.
--- Ability to keep only the caps (top and bottom) or only sides of characters.
The yuqk fork adds two new features to the text{} object in 'open' and 'caps'.
These allow users to keep only the character sides or only the character caps
(ends / top and bottom surfaces). These features allow for different texturing
to be applied to the ends versus the sides, for example.
The caps option may be:
caps
or
caps on
or
caps off
The open option may be:
open
or
open on
or
open off
Though it is more common to use only one of the features: 'open' or 'caps',
both can be specified. In such cases the last specified wins where it changes
the prior selection of surface intersections returned.
- If both are set off or on, all surface intersections are returned.
- open off -> caps on (caps wins; only top and bottom intersections)
- open on -> caps off (caps wins; all surface intersections)
- caps off -> open on (open wins; only side intersections)
- caps on -> open off (open wins; all surface intersections)
Note. The keywords 'caps' and/or 'open' must follow the offset vector
specification.
Defaults:
---------
The default settings:
merge - Not specified. The text{} object creates and internal union{}.
This is equivalent to specifying 'merge off'.
open - Not specified. Return the caps / ends / top and bottom surface
intersections and the sides. This is equivalent to 'open off'.
caps - Not specified. Return the side surface intersections along with
the cap / end intersections. This is equivalent to 'caps off'.
Description:
------------
The following description partly taken from:
https://wiki.povray.org/content/Reference:Text
and
https://wiki.povray.org/content/Documentation:Tutorial_Section_3#Index_Entry_text_tutorial
A text{} object creates 3-D text as extruded set characters, or 2D text as a
set of surfaces, using a font file and text-string inputs.
The 3D (or 2D) object created can be used along with shapes like spheres and
cylinders as full fledged objects. The 3D output has a defined inside. As such
they may be used with Constructive Solid Geometry (CSG) features, be
transformed and general object modifiers like 'hollow' and 'no_shadow' may be
used.
Currently only TrueType Fonts are supported whether found in .ttf or .ttc files.
Characters are generally sized so that 1 unit of vertical spacing is correct.
The characters usually consume 0.5 to 0.75 units horizontally in western fonts
with varying horizontal space - except in mono fonts. More generally, fonts are
usually smaller horizontally than vertically or at most square, but the font
defines the relative character sizes and spacings.
Normally, the text will start with the origin at the lower left, the front of
the first character and will extend in the +x-direction. The baseline of the
text follows the x-axis and descender drop into the -y-direction. The front of
the character sits in the x-y-plane and the text is extruded in the
+z-direction. The front-to-back (or back to front) thickness is specified by
the required thickness value.
The thickness value is normally positive. It can also be negative or zero. When
negative the text is extruded in the -z direction and the normals of the cap
surfaces is inverted.
When the thickness is 0 the inside test will always return false. Further, the
code set up expects the user will normally be using the - new to yuqk - 'caps'
or 'caps on' option which returns only the top cap when the thickness is zero.
In other words, users can now get true 2D surfaces from the text{} object.
The horizontal spacing is handled by POV-Ray internally including most kerning
information stored in the font. The required 3D vector <Offset> defines any
translation between each character. With mono fonts it can be used to arrange
the text vertically or so the characters run right to left (backwards).
Normally you should specify a zero for this 3D vector value. Specifying 0.1*x,
for example, would put additional 0.1 units of space between each character.
Specifying 0.0001*z, might be used to prevent coincident surfaces where a font
overlaps adjacent characters.
Here's an example:
text {
ttf "timrom.ttf" "POV-Ray (yuqk)" 1, 0
pigment { rgb <1,0,0> }
}
Note. Currently POV-Ray (yuqk) supports Unicode characters in the Basic
Multilingual Plane (BMP). In other words characters with decimal values of 0 to
65535 (Hexadecimal #0000 to #FFFF).
TrueType Font (.ttf) files vs TrueType Collection (.ttc) files
--------------------------------------------------------------
Input files can be stand alone TrueType Font files (.ttf) consisting of one
style of the font. Or input files may be TrueType Collections (.ttc) containing
multiple styles of the same font, or multiple derivative fonts of the same
style or combinations thereof. However, with collections POV-Ray always uses
the first TrueType font in the collection(*).
(*) - Which can introduce instability over time should the collection ship
later with a changed ordering of internal TrueType fonts.
Using the LiberationMono font as an example, the styles of the font can be
provided as individual .ttf files:
/home/pokorny/Fonts/LiberationMono-Regular.ttf
/home/pokorny/Fonts/LiberationMono-Italic.ttf
/home/pokorny/Fonts/LiberationMono-Bold.ttf
/home/pokorny/Fonts/LiberationMono-BoldItalic.ttf
Or those four styles could be packed into a single .ttc collection:
/home/pokorny/Fonts/LiberationMono.ttc
Note! The .ttc suffix is used for collections which are NOT TrueType fonts
and so not currently supported by POV-Ray's text{} object. For example,
many linux distribution have CJK fonts like:
/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc
Tip. If running on a Linux or Unix system and you have copied or downloaded a
font collection file locally and you want to know whether it contains TrueType
fonts, you can use the command:
file NotoSansCJK-Regular.ttc
-------------------------------
General yuqk fork modifications
-------------------------------
Over the years the yuqk fork has made a number of internal modifications to the
code to make it faster and more robust. See the issues section below for more
detail about bug fixes and remaining issues.
a) The quadratic solver was changed to a version from CERN which is
usually faster and always more accurate.
b) Two changes which improve inside test performance. One of which more
generally applies to unions{} which are created by the text{} object.
----
Tips
----
Quick hack for somewhat border characters
-----------------------------------------
It's a hack, but you can get somewhat of a bordered character effect in POV-Ray
where you are using a font which offers different styles like regular, bold,
italic and bolditalic.
You can quickly place additional text{} objects with differing fonts slightly
behind the regular style font. For example, placing a text{} object using the
bold style just behind the text{} object using the regular style.
Because of how fonts typically work they are often constrained vertically. This
means for 3D shape applications over 2D there may well be coincident surfaces
which could cause problems. It's a hack - but a quick one.
More robust bordered characters
-------------------------------
There is also the dens_object{} pattern in the yuqk fork which can in
many cases implement a good bordered character - or bordered any object
with a defined inside. See:
https://news.povray.org/povray.binaries.images/thread/%3C64f53f14%241%40news.povray.org%3E/
Names and data for Unicode characters
-------------------------------------
See: https://www.unicode.org/Public/UCD/latest/ucd/NamesList.txt
The Unicode indexing is usually by hexadecimal values rather than the decimal
value we'd pass to chr() in a scene. See conversion and specification methods
just below.
---------
Examples:
---------
Does your font file support a particular Unicode character? For example, the
euro symbol (€). It's decimal value is 8364 (The hexadecimal value is 20AC).
//---
// yuqk isFontCharSupported.pov +mv3.8 +w400 +h400 +a +p
text {
ttf "timrom.ttf"
chr(8364) // Or chr(val("0x20AC"))
//chr(val(S)) // On command line add declare=S=\"0x20AC\"
//"€" // OK.
//"\u20AC" // OK.
//chr(asc("€")) // OK.
0.01, 0
pigment { rgb <1,0,0> }
finish { emission 1 }
scale 0.2
translate <0,0,2>
}
// timrom.ttf (No)
// LiberationMono-Regular.ttf (Yes)
//---
---
// Sample scene.
// yuqk monoBoxChars.pov +w800 +h800 +p
// As animation:
// yuqk monoBoxChars.pov +w800 +h800 +p +kff10
#version unofficial 3.8; // yuqk
#if (file_exists("version.inc"))
#include "version.inc"
#end
#if (!defined(Fork_yuqk))
#error "This POV-Ray SDL code requires the yuqk fork."
#end
global_settings { assumed_gamma 1.0 }
#declare VarOrthoMult =
3.0/max(image_width/image_height,image_height/image_width);
#declare Camera01z = camera {
orthographic
location <0,0,-2>
direction z
right VarOrthoMult*x*max(1,image_width/image_height)
up VarOrthoMult*y*max(1,image_height/image_width)
}
#include "functions.inc"
// Liberation fonts usually ship with Linux distributions.
// Use command: 'fc-list | grep LiberationMono' to find
// the location on your computer.
#declare
// FontFile = "/home/pokorny/Fonts/LiberationMono-Regular.ttf"
FontFile = "/home/pokorny/Fonts/UbuntuMono-R.ttf"
#declare BoxChars = "─│┌┐└┘├┤┬┴┼┼┼┼┼─│"
#declare RndSd = seed(f_clock(0,0,0)*1e2);
#declare Rows = 12;
#declare Cols = 20;
#declare Ary = array[Rows]
#for (R,0,Rows-1,1)
#declare Ary[R] = concat(
#for (C,0,Cols-1,1)
substr(BoxChars,int(1+rand(RndSd)*(10-1e-6)),1),
#end
"")
#end
plane { -z 0
pigment {
bool_object {
#for (R,0,Rows-1,1)
text { ttf FontFile Ary[R] 1,0 translate <0,6-(1*R),0> }
#end
pigment { rgb 0 }
pigment { rgb <1,1,0> }
}
scale <1/5,1/5,1>
translate <-1,-0.1,-0.5>
}
finish { emission 1 }
}
camera { Camera01z }
//---
---
// Sample scene.
// 'yuqk textDirections.pov +w800 +h800 +p'
// With mono fonts right to left and vertical text{}s possible
#version unofficial 3.8; // yuqk
#if (file_exists("version.inc"))
#include "version.inc"
#end
#if (!defined(Fork_yuqk))
#error "This POV-Ray SDL code requires the yuqk fork."
#end
global_settings{ assumed_gamma 1 }
#declare VarOrthoMult =
12.0/max(image_width/image_height,image_height/image_width);
#declare Camera01z = camera {
orthographic
location <0,0,-2>
direction z
right VarOrthoMult*x*max(1,image_width/image_height)
up VarOrthoMult*y*max(1,image_height/image_width)
}
// Liberation fonts usually ship with Linux distributions.
// Use command: 'fc-list | grep LiberationMono' to find
// the location on your computer.
#declare FontFile =
"/home/pokorny/Fonts/LiberationMono-Regular.ttf"
// "/home/pokorny/Fonts/LiberationMono-BoldItalic.ttf"
// "/home/pokorny/Fonts/UbuntuMono-R.ttf"
// Use Chris R method to determine character pitches
#local _T1 = text { ttf FontFile "A" 1.0, 0 }
#local _T2 = text { ttf FontFile "AA" 1.0, 0 }
#local _T3 = text { ttf FontFile "│" 1.0, 0 }
#local _T1sz = max_extent(_T1) - min_extent(_T1);
#local _T2sz = max_extent(_T2) - min_extent(_T2);
#local _T3sz = max_extent(_T3) - min_extent(_T3);
#declare _Cwidth = (_T2sz - _T1sz).x;
#declare _Cheight = _T3sz.y;
#declare TxtRight = text {
ttf FontFile
"ABCDEFGHIJ", 2e-6, <0,0,0>
//rotate <0,0,1e-6> // User fixes axis aligned artefacts
translate <-5*_Cwidth,+_Cheight+(_Cheight/4),-1e-6>
}
#declare TxtLeft = text {
ttf FontFile
"ABCDEFGHIJ", 2e-6, <-2*_Cwidth,0,0>
//rotate <0,0,1e-6> // User fixes axis aligned artefacts
translate <+4*_Cwidth,-2*_Cheight+(_Cheight/4),-1e-6>
}
#declare TxtDown = text {
ttf FontFile
"ABCDEFGHIJ", 2e-6, <-_Cwidth,-_Cheight,0>
//rotate <0,0,1e-6> // User fixes axis aligned artefacts
translate <-7*_Cwidth,+4*_Cheight+(_Cheight/4),-1e-6>
}
#declare TxtUp = text {
ttf FontFile
"ABCDEFGHIJ",2e-6, <-_Cwidth,+_Cheight,0>
//rotate <0,0,1e-6> // User fixes axis aligned artefacts
translate <+6*_Cwidth,-5*_Cheight+(_Cheight/4),-1e-6>
}
#declare Fn = function {
pattern {
bool_object {
TxtRight
TxtLeft
TxtDown
TxtUp
}
warp { it_amount <0.05,0.05,0> it_lambda 4 it_scale 0.9}
}
}
#include "functions.inc"
plane { -z 0
pigment {
#if (0)
bool_object {
TxtRight
TxtLeft
TxtDown
TxtUp
}
warp {
it_amount <0.05,0.05,0>
it_octaves 3
it_omega 0.9
it_lambda 7
it_scale 1.7
}
#elseif (0)
function { Fn(x,y,z) }
#else
function { Fn(x,y,z)*(f_popnrm_rnoise(x,y,z,now,1)+1.0) }
inverse
#end
}
finish { emission 1 }
}
camera { Camera01z }
sphere { 0, 0.5 pigment { rgbt <1,0,0,0.7> } finish { emission 1 } }
---
// Sample scene.
// yuqk outLineFontMethod.pov +w800 +h800 +p
// Using negative area light projected through text cap to turn
// any font into an apparent outline font.
#version unofficial 3.8; // yuqk
#if (file_exists("version.inc"))
#include "version.inc"
#end
#if (!defined(Fork_yuqk))
#error "This POV-Ray SDL code requires the yuqk fork."
#end
global_settings { assumed_gamma 1.0 }
#declare VarOrthoMult =
5.0/max(image_width/image_height,image_height/image_width);
#declare Camera01z = camera {
orthographic
location <0,0,-2>
direction z
right VarOrthoMult*x*max(1,image_width/image_height)
up VarOrthoMult*y*max(1,image_height/image_width)
}
// Liberation fonts usually ship with Linux distributions.
// Use command: 'fc-list | grep LiberationMono' to find
// the location on your computer.
#declare
// FontFile = "/home/pokorny/Fonts/LiberationMono-Regular.ttf"
FontFile = "/home/pokorny/Fonts/UbuntuMono-R.ttf"
#declare String = "outline"
// Use Chris R method to determine character pitches
#local _T1 = text { ttf FontFile "A" 1.0, 0 }
#local _T2 = text { ttf FontFile "AA" 1.0, 0 }
#local _T3 = text { ttf FontFile "│" 1.0, 0 }
#local _T1sz = max_extent(_T1) - min_extent(_T1);
#local _T2sz = max_extent(_T2) - min_extent(_T2);
#local _T3sz = max_extent(_T3) - min_extent(_T3);
#declare _Cwidth = (_T2sz - _T1sz).x;
#declare _Cheight = _T3sz.y;
#declare TxtRight = text {
ttf FontFile
String, 0, <0,0,0>
caps on // At depth of 0 get 2D top cap only
translate <-3.5*_Cwidth,-_Cheight/4,0>
}
#declare Text00 = object {
TxtRight
pigment { rgb <1,1,0> }
finish { emission 1 }
interior_texture {
pigment { rgb <0,1,1> }
finish { emission 1 }
}
translate <0.0,0.0,-0.5>
}
#declare Light00 = light_source {
<0,0,-10>, rgb -5
parallel
point_at <0,0,0>
projected_through {
union {
object { TxtRight translate <0,+1,-0.5> }
object { TxtRight translate <0,+0,-0.5> }
object { TxtRight translate <0,-1,-0.5> }
}
}
area_light 3*x,5*y,33,55
adaptive 1
jitter circular orient
}
//---
camera { Camera01z }
light_source { Light00 }
plane { -z 0
pigment { rgb 1 }
finish { emission 1 diffuse 1}
}
union {
object { Text00 translate <0,+2,0> }
object { Text00 translate <0,+1,0> }
object { Text00 translate <0,+0,0> }
object { Text00 translate <0,-1,0> }
object { Text00 translate <0,-2,0> }
}
---
// Sample scene.
// yuqk caps_open_features.pov +w800 +h800 +p
#version unofficial 3.8; // yuqk
#if (file_exists("version.inc"))
#include "version.inc"
#end
#if (!defined(Fork_yuqk))
#error "This POV-Ray SDL code requires the yuqk fork."
#end
global_settings { assumed_gamma 1.0 }
#declare Camera00 = camera {
perspective
location <1,0.3,-3.001>*0.7
sky y
angle 35
right x*(image_width/image_height)
look_at <0,0,0>
}
#declare VarOrthoMult =
5.0/max(image_width/image_height,image_height/image_width);
#declare Camera01z = camera {
orthographic
location <0,0,-2>
direction z
right VarOrthoMult*x*max(1,image_width/image_height)
up VarOrthoMult*y*max(1,image_height/image_width)
}
#declare White = srgb <1,1,1>;
#declare Light00 = light_source { <50,150,-250>, White }
#declare Red = srgb <1,0,0>;
#declare CylinderX = cylinder { -1*x, 1*x, 0.01 pigment { Red } }
#declare Green = srgb <0,1,0>;
#declare CylinderY = cylinder { -1*y, 1*y, 0.01 pigment { Green } }
#declare Blue = srgb <0,0,1>;
#declare CylinderZ = cylinder { -1*z, 1*z, 0.01 pigment { Blue } }
// Liberation fonts usually ship with Linux distributions.
// Use command: 'fc-list | grep LiberationMono' to find
// the location on your computer.
#declare
// FontFile = "/home/pokorny/Fonts/LiberationMono-Regular.ttf"
FontFile = "/home/pokorny/Fonts/UbuntuMono-R.ttf"
#declare String = "XYZ 123"
// Use Chris R method to determine character pitches
#local _T1 = text { ttf FontFile "A" 1.0, 0 }
#local _T2 = text { ttf FontFile "AA" 1.0, 0 }
#local _T3 = text { ttf FontFile "│" 1.0, 0 }
#local _T1sz = max_extent(_T1) - min_extent(_T1);
#local _T2sz = max_extent(_T2) - min_extent(_T2);
#local _T3sz = max_extent(_T3) - min_extent(_T3);
#declare _Cwidth = (_T2sz - _T1sz).x;
#declare _Cheight = _T3sz.y;
#declare TxtrO = texture {
pigment { rgb <0.5,0.5,0> }
finish { emission <0.1,0,0> }
}
#declare TxtrI = texture {
pigment { rgb <0,0.5,0.5> }
finish { emission <0,0.1,0> }
}
#declare Depth = 1;
#declare TxtPosThickness = text {
ttf FontFile
String, +Depth, <0,0,0>
texture { TxtrO }
interior_texture { TxtrI }
translate <-3.5*_Cwidth,-_Cheight/4,0>
}
#declare TxtNegThickness = text {
ttf FontFile
String, -Depth, <0,0,0>
texture { TxtrO }
interior_texture { TxtrI }
translate <-3.5*_Cwidth,-_Cheight/4,0>
}
#declare TxtPosThickness_caps = text {
ttf FontFile
String, +Depth, <0,0,0>
caps on
texture { TxtrO }
interior_texture { TxtrI }
translate <-3.5*_Cwidth,-_Cheight/4,0>
}
#declare TxtNegThickness_caps = text {
ttf FontFile
String, -Depth, <0,0,0>
caps on
texture { TxtrO }
interior_texture { TxtrI }
translate <-3.5*_Cwidth,-_Cheight/4,0>
}
#declare TxtPosThickness_open = text {
ttf FontFile
String, +Depth, <0,0,0>
open on
texture { TxtrO }
interior_texture { TxtrI }
translate <-3.5*_Cwidth,-_Cheight/4,0>
}
#declare TxtNegThickness_open = text {
ttf FontFile
String, -Depth, <0,0,0>
open on
texture { TxtrO }
interior_texture { TxtrI }
translate <-3.5*_Cwidth,-_Cheight/4,0>
}
#declare U00 = union {
object { TxtPosThickness translate <0,+5*_Cheight,0> }
object { TxtNegThickness translate <0,+4*_Cheight,0> }
object { TxtPosThickness_caps translate <0,+3*_Cheight,0> }
object { TxtNegThickness_caps translate <0,+2*_Cheight,0> }
object { TxtPosThickness_open translate <0,+1*_Cheight,0> }
object { TxtNegThickness_open translate <0,+0*_Cheight,0> }
translate <0,-2.5*_Cheight,0>
scale 0.2
}
//---
camera { Camera00 }
// camera { Camera01z }
light_source { Light00 }
#if (1)
object { U00 }
#elseif (0)
intersection { // negative thickness text{}
object { U00 }
box { <-1,-1,-0.10>,<+1,+1,-0.05> }
}
#elseif (0)
intersection { // positive thickness text{}
object { U00 }
box { <-1,-1,+0.05>,<+1,+1,+0.10> }
}
#end
sphere { 0, 0.005 pigment { rgb 0.2 } }
---
//---
// Sample scene.
// yuqk monoFontFileMovie.pov +w900 +h450 +p
// Final frames:
// yuqk monoFontFileMovie.pov +w900 +h450 -p -d +kff1311 \
// +a0.002 +am3 +rd3 +rd5 +j1.1
// Creating an mp4 movie of all the characters defined in the Basic
// Multilingual Plane (BMP) for a mono font file.
//
// Note. Character image compares are done here with POV-Ray (yuqk)
// SDL during parsing. Expect the entire 1311 frames to take hours.
// To render, say only the first 20 frames (1000 characters) add the
// flags: +sf1 +ef20 to the final frames command above.
#version unofficial 3.8; // yuqk
#if (file_exists("version.inc"))
#include "version.inc"
#end
#if (!defined(Fork_yuqk))
#error "This POV-Ray SDL code requires the yuqk fork."
#end
global_settings { assumed_gamma 1.0 }
#declare VarOrthoMult =
4.0/max(image_width/image_height,image_height/image_width);
#declare Camera01z = camera {
orthographic
location <0,0,-2>
direction z
right VarOrthoMult*x*max(1,image_width/image_height)
up VarOrthoMult*y*max(1,image_height/image_width)
}
// Liberation fonts usually ship with Linux distributions.
// Use command: 'fc-list | grep LiberationMono' to find
// the location on your computer.
#declare
// FontFile = "/home/pokorny/Fonts/LiberationMono-Regular.ttf"
FontFile = "/home/pokorny/Fonts/UbuntuMono-R.ttf"
// FontFile = "/home/pokorny/Fonts/Hack-Regular.ttf"
// Use Chris R method to determine character pitches
#local _T1 = text { ttf FontFile "A" 1.0, 0 }
#local _T2 = text { ttf FontFile "AA" 1.0, 0 }
#local _T3 = text { ttf FontFile "│" 1.0, 0 }
#local _T1sz = max_extent(_T1) - min_extent(_T1);
#local _T2sz = max_extent(_T2) - min_extent(_T2);
#local _T3sz = max_extent(_T3) - min_extent(_T3);
#declare _Cwidth = (_T2sz - _T1sz).x;
#declare _Cheight = _T3sz.y;
#local CharsPerPage = 50;
#local I = max(0,frame_number-1)*CharsPerPage;
#local I = min(65535-CharsPerPage+1,I);
#local Str00n = concat( "|",str(I+ 0,-5,0),"|",str(I+ 1,-5,0),"|",str(I+ 2,-5,0),"|",str(I+ 3,-5,0),"|",str(I+ 4,-5,0),"|",str(I+ 5,-5,0),"|",str(I+ 6,-5,0),"|",str(I+ 7,-5,0),"|",str(I+ 8,-5,0),"|",str(I+ 9,-5,0),"|")
#local Str01n = concat( "|",str(I+10,-5,0),"|",str(I+11,-5,0),"|",str(I+12,-5,0),"|",str(I+13,-5,0),"|",str(I+14,-5,0),"|",str(I+15,-5,0),"|",str(I+16,-5,0),"|",str(I+17,-5,0),"|",str(I+18,-5,0),"|",str(I+19,-5,0),"|")
#local Str02n = concat( "|",str(I+20,-5,0),"|",str(I+21,-5,0),"|",str(I+22,-5,0),"|",str(I+23,-5,0),"|",str(I+24,-5,0),"|",str(I+25,-5,0),"|",str(I+26,-5,0),"|",str(I+27,-5,0),"|",str(I+28,-5,0),"|",str(I+29,-5,0),"|")
#local Str03n = concat( "|",str(I+30,-5,0),"|",str(I+31,-5,0),"|",str(I+32,-5,0),"|",str(I+33,-5,0),"|",str(I+34,-5,0),"|",str(I+35,-5,0),"|",str(I+36,-5,0),"|",str(I+37,-5,0),"|",str(I+38,-5,0),"|",str(I+39,-5,0),"|")
#local Str04n = concat( "|",str(I+40,-5,0),"|",str(I+41,-5,0),"|",str(I+42,-5,0),"|",str(I+43,-5,0),"|",str(I+44,-5,0),"|",str(I+45,-5,0),"|",str(I+46,-5,0),"|",str(I+47,-5,0),"|",str(I+48,-5,0),"|",str(I+49,-5,0),"|")
#if (strlen(chr(I+0))!=1) // Special handling for null character
#local Chr00 = " " // Also useful for image character comparisons
#else
#local Chr00 = chr(I+0)
#end
#local Str00c = concat( "| ", Chr00," | ",chr(I+ 1)," | ",chr(I+ 2)," | ",chr(I+ 3)," | ",chr(I+ 4)," | ",chr(I+ 5)," | ",chr(I+ 6)," | ",chr(I+ 7)," | ",chr(I+ 8)," | ",chr(I+ 9)," |")
#local Str01c = concat( "| ",chr(I+10)," | ",chr(I+11)," | ",chr(I+12)," | ",chr(I+13)," | ",chr(I+14)," | ",chr(I+15)," | ",chr(I+16)," | ",chr(I+17)," | ",chr(I+18)," | ",chr(I+19)," |")
#local Str02c = concat( "| ",chr(I+20)," | ",chr(I+21)," | ",chr(I+22)," | ",chr(I+23)," | ",chr(I+24)," | ",chr(I+25)," | ",chr(I+26)," | ",chr(I+27)," | ",chr(I+28)," | ",chr(I+29)," |")
#local Str03c = concat( "| ",chr(I+30)," | ",chr(I+31)," | ",chr(I+32)," | ",chr(I+33)," | ",chr(I+34)," | ",chr(I+35)," | ",chr(I+36)," | ",chr(I+37)," | ",chr(I+38)," | ",chr(I+39)," |")
#local Str04c = concat( "| ",chr(I+40)," | ",chr(I+41)," | ",chr(I+42)," | ",chr(I+43)," | ",chr(I+44)," | ",chr(I+45)," | ",chr(I+46)," | ",chr(I+47)," | ",chr(I+48)," | ",chr(I+49)," |")
#declare Text00n = text { ttf FontFile Str00n, 1.0, 0 translate <0,+0*_Cheight,-0.5> }
#declare Text00c = text { ttf FontFile Str00c, 1.0, 0 translate <0,-1*_Cheight,-0.5> }
#declare Text01n = text { ttf FontFile Str01n, 1.0, 0 translate <0,-2*_Cheight,-0.5> }
#declare Text01c = text { ttf FontFile Str01c, 1.0, 0 translate <0,-3*_Cheight,-0.5> }
#declare Text02n = text { ttf FontFile Str02n, 1.0, 0 translate <0,-4*_Cheight,-0.5> }
#declare Text02c = text { ttf FontFile Str02c, 1.0, 0 translate <0,-5*_Cheight,-0.5> }
#declare Text03n = text { ttf FontFile Str03n, 1.0, 0 translate <0,-6*_Cheight,-0.5> }
#declare Text03c = text { ttf FontFile Str03c, 1.0, 0 translate <0,-7*_Cheight,-0.5> }
#declare Text04n = text { ttf FontFile Str04n, 1.0, 0 translate <0,-8*_Cheight,-0.5> }
#declare Text04c = text { ttf FontFile Str04c, 1.0, 0 translate <0,-9*_Cheight,-0.5> }
// Because almost all fonts are sparsely implemented in the BMP, do some work to
// create completely black images where characters are defaulting to some common glyph.
#local _TCmp1 = text { ttf FontFile Chr00 1.0, 0 translate -0.5*z }
#declare FnBaseImg = function { pattern { bool_object {_TCmp1} } }
#local Resolution = 199;
#local InvDelta = 1.0/(Resolution-30);
#local Matched = true;
#for (KK,I+1,I+CharsPerPage-1,1)
#local KK = min(65535,KK);
#if (strlen(chr(KK))!=1)
#error concat("ERROR! Saw strlen() other than 1 at character ",str(KK,5,0),"\n")
#end
#local _TCmp2 = text { ttf FontFile chr(KK) 1.0, 0 translate -0.5*z }
#if (defined(FnTestImg))
#undef FnTestImg
#end
#declare FnTestImg = function { pattern { bool_object {_TCmp2} } }
#for (YY,-50,Resolution,1)
#for (XX,-50,Resolution,1)
#if ( FnBaseImg(XX*InvDelta,YY*InvDelta,0) != FnTestImg(XX*InvDelta,YY*InvDelta,0))
#local Matched = false;
//#debug concat("Failed match at XX = ",str(XX,4,0)," YY = ",str(YY,4,0),"\n")
#end
#if (!Matched)
#break
#end
#end
//#debug concat("YY = ",str(YY,4,0),"\n")
#if (!Matched)
#break
#end
#end
#end
#undef KK
#if (!Matched)
plane { -z 0
pigment {
bool_object {
Text00n
Text00c
Text01n
Text01c
Text02n
Text02c
Text03n
Text03c
Text04n
Text04c
pigment { rgb <0,0,0> }
pigment { rgb <0,1,0> }
}
translate <-(max_extent(Text00n)-min_extent(Text00n)).x/2.0,5*_Cheight-0.5,0>
scale 0.1
}
finish { emission 1 }
}
#end
camera { Camera01z }
//---
// The following ReduceFontFrames.tcl script is one way to extract
// non-black frames for the final animation.
// #!/usr/bin/tclsh
// # ReduceFontFrames.tcl
// # This TCL script set up to run after 1311 frames of 50 characters each have
// # been rendered to images covering the Basic Multilingual Plane (BMP) for
// # a given mono-pitch font. Frames for which no character glyphs exist are
// # rendered black and have a small size. Frame images with at least one
// # character having glyphs are rendered as a table and have a larger size
// #
// # We use this size difference to create a subset of frames with indexes
// # from 1 to N of the table versions. Only these frames become part of an
// # mp4 animation encoded with ffmpeg.
// #
// # The mp4 animation can be viewed to review the characters supported by
// # the particular font file.
// #
// # After this script runs (./ReduceFontFrames.tcl) there will be files of
// # the form: monoFontFileMovie__001.png, monoFontFileMovie__002.png, ...
// #
// # Use the ffmpeg program to turn the reduced collection of frames into a
// # mp4 movie at a frame per second:
// #
// # fmpeg -y -r 1 -i monoFontFileMovie__%3d.png -pix_fmt yuv420p -strict -2 UbuntuMonoR.mp4
// #
// # View with: 'ffplay UbuntuMonoR.mp4', your web browser or other mp4 viewing
// # program.
// #
// set tmpdirVal [pwd]
// set tmpList [glob -directory $tmpdirVal -nocomplain monoFontFileMovie????.png]
// puts "Number of frames found: [llength $tmpList]"
// set keepList [list]
// set ignoreList [list]
// foreach filename $tmpList {
// if { [file size $filename] < 5000 } {
// lappend ignoreList $filename
// } else {
// lappend keepList $filename
// }
// }
// puts "Keeping [llength $keepList] frames images"
// set cnt 1
// foreach filename $keepList {
// set rootName [file rootname $filename]
// set rootName [string range $rootName 0 [expr {[string length $rootName]-5}] ]
// set newFileName [format {%s__%03d.png} $rootName $cnt]
// incr cnt
// puts "copy $filename to $newFileName"
// file copy -force $filename $newFileName
// }
// exit 0;
---
Issues:
-------
While an attempt has been made to list bugs and fixes first, the following list
of issues is in no particular order of importance.
---
a) The yuqk fork fixed a forever standing bug with diacritical marks as
implemented (correctly) by many fonts. This means the yuqk fork renders these
characters correctly where official POV-Ray releases often do not.
See:
https://news.povray.org/povray.binaries.images/thread/%3C63cd6b12%241%40news.povray.org%3E/
https://news.povray.org/povray.beta-test/thread/%3C642f33e8%241%40news.povray.org%3E/
b) The z component of the offset vector was not implemented correctly in any
relatively recent official release of POV-Ray. A tiny z offset is necessary
where fonts are set up such that adjacent characters slightly overlap after
kerning and placement. We end up with coincident front and back surfaces
without the z offset capability. This is fixed in the yuqk fork. Note.
Occasionally a small y offset is necessary too - which does work in official
POV-Ray releases.
c) Official releases of POV-Ray do not correctly implement negative thickness.
It only partly works for the caps / ends / (top and bottom) surface
intersections. The yuqk fork supports negative thickness values.
d) The yuqk fork has fixed an occasional segmentation fault / memory addressing
bug during parsing which exists in some v3.8 and v4.0 versions of POV-Ray. The
failure rate was on the order of maybe 1/1000 parse time interpretations of
text{} objects.
See:
https://news.povray.org/povray.bugreports/thread/%3C67cc705e%40news.povray.org%3E/
e) The yuqk fork has used v4.0 changes, backed out of the v3.8 beta releases,
which allow more utf8 / Unicode characters to render correctly. This true
especially on Linux / Unix machines.
These v4.0 changes to text{} were part of a larger group fixes made by
Christoph Lipka (aka clipka) during v3.8 development in an effort to improve
Unicode support for the Basic Multilingual Plane (BMP) within POV-ray. I do not
know the complete details of these changes.
For example, using the isFontCharSupported.pov example scene above and the
"LiberationMono-Regular.ttf" font file shipped with my Ubuntu 24.04 Linux
machine, the yuqk fork correctly renders the "│" / char(9474) / hexadecimal
0x2502 Unicode character - where the official v3.8 beta 2 release does not.
f) There is a tiny rotation applied always to text{} objects of
<0.001,0.001,0.001> with all official releases of POV-Ray. The rotation was
apparently added to eliminate axis aligned numerical seams creating artefacts.
The hidden rotation, of course, introduces placement and positioning noise.
Noise which is magnified as the text{} object's string length grows. This
another reason in official POV-Ray releases that breaking long strings up into
separate single character text{} objects can be useful.
Reference:
https://news.povray.org/povray.pov4.discussion.general/thread/%3C67d31e6b%241%40news.povray.org%3E/
As of release R19 of yuqk, this rotation has been removed as a trial. In
testing no numerical artefacts were seen. The thinking is the user should
always have been left with the fixes here as is done for other numerical
situations like avoiding coincident surfaces.
Should numerical artefacts appear the user can always add the same rotation
themselves - but it's very likely they can find some more minimal transform to
achieve the same result.
g) The yuqk fork moved to the same CERN quadratic server code for ttf fonts as
is used for many shapes. It's generally faster - and in being more accurate
will have addressed / fixed some numerical artefacts.
The text{} truetype shape code maintained it's own quadratic solver with a very
aggressive skip of second possible root method - if the first of dual roots was
outside the [0..1] range. The shortcut helped almost exclusively 'orthographic
rays to text character face' scenes. In testing there were very few missed
roots, but missed they were... It's a cool trick, but both one not available
with the CERN version and it carries risk as it does sometimes miss valid
roots.
The new solver is faster and more accurate in testing - excepting slower for
that particular orthographic ray to text character case where it is 4-5%
slower.
h) The inside test as it relates to the winding test used by POV-Ray differs
from that defined for ttf fonts. The winding test checks for the number of
crossing of a splines path from a evaluation point in space direction. Where
the crossing count is even the evaluation point is seen as outside the overall
region as defined by the splines.
This method works well and specifically allows holes (or bites) to be cut in
larger spline loops by loops wholly contained or partly overlapping.
TrueType fonts allow curve loops to overlap in an additive way. Though most
font implementations don't overlap loops - probably so they work with programs
like POV-Ray too.
Where fonts contain character glyphs which have loops that overlap, these will
not be correctly rendered correctly in total. Often the overlaps are quite
small and not very noticeable. There is no fix or work around in these cases -
other than using another font implementation.
i) Bounding. The POV-Ray code creates an internal union{} object with a single
bounding box from all the individual characters in the passed text{}'s string.
The yuqk fork can optionally create an internal merge{} instead.
For most ray tracing aspects, the overall union{}s containing individual
characters are flattened and bounded individually - leading to better
performance. The merge{}s are treated whole and as merges have some unresolved
bounding issues I've not enumerated herein - use merge{}s only when needed.
For inside testing(*) the union{} hierarchy is not flattened and this testing
can be slow - especially for something like the text{} object. The yuqk fork
has a couple of internal enhancements which speed up the text{}'s union{}
inside testing - and one of them should help across all union{}s of objects.
(*) - Note. The bounding tests part of inside testing do not get recorded or
reported in POV-Ray's statistics.
Note! Even with the yuqk inside test enhancements, it can be a render time win
to break long strings in single character text{} objects (which still end up as
union{}s or merge{}s internally). Of course, this leaves the character to
character placement to the user, and for complicated overlapping character
fonts it might not be practical.
j) There are small fudge factors due bounding which can cause differences when
trying to align, say, box drawing characters by transform with respect to
portions 'placed' by inclusion in a longer passed string. It might be in some
cases ones needs to do all placements by explicit transform or by using all
longer text{} strings (this last works better in yuqk do the elimination of the
hidden rotation).
k) There are small differences in the specified font accuracy coming into POV-Ray
too. In all fonts there is in the Font Header section a setting of:
unitsPerEm: <number>
Google AI says: "In TrueType fonts, "units per em" (UPM) refers to the number
of font units that define the height of the "em square," a fundamental metric
for font design and scaling, often set to 2048."
I don't routinely pay attention to this value when using fonts, but I've
noticed settings of 1000, 1024 and 2048. The value matters because it is used
within POV-Ray to normalize each all the character glyph contours (Bezier
quadratic piecemeal loops in the ttf fonts) to fit roughly within a +x+y unit
square (though the characters are rarely square in western fonts). The lower
that unitsPerEm value and the lower the accuracy of POV-Ray's normalization.
Further, fonts often have differing height to width aspect ratios - which
itself can affect accuracy of the internal glyphs on POV-Ray's normalization.
l) The text{} object today only handles TrueType Fonts (ttf / <filename>.ttf).
m) The official documentation for POV-Ray claims it can read TrueType
Collection (.ttc) files containing multiple fonts. It in fact has never been
able to work with more than the first font in the collection. Not being able to
set which font to use with .ttc files makes their use iffy over time.
Note! Not all .ttc files contain true type coded fonts. Some, for example,
contain open type fonts which are not today supported.
n) Even at character screen sizes which might normally be read, some characters
(or some entire fonts - such as 'hairline' fonts) do not render cleanly. The
shading characters such as: chr(9608),chr(9617),chr(9618) and chr(9619) are
made up of very small shapes or holes, as another example.
Where the detail is too small to be reliably picked up; The yuqk fork's +rd n /
anti-alias_min_depth=n option can render these cleanly. The jitter option can
sometimes help too, but it can be problematic too in that statistically it can
still miss small features - and where it doesn't - it plays slightly with final
intensity which results in larger stored images and animations (they compress
less well).
In POV-Ray proper, the only clean option in these cases is to render at a
larger image size that is scaled down to a final presentation size.
o) Though some horizontal kerning is supported. Good fonts often have
additional kerning features, hinting / auto-hinting with tiny programming
kernels which are not supported by the POV-Ray's true type shape
implementation. This means for some fonts, and some characters, the appearance
in a good word processor or type setting program may be better / differ from
what is seen for POV-Ray results.
p) An ability to create an internal merge{} of character objects, rather than
only a union{} of character objects from the text{} string has also long been
missing. With the yuqk fork, tfhe keyword 'merge' or 'merge on|off' can be
specified within the text{} block.
Reference:
https://news.povray.org/povray.binaries.animations/thread/%3C67dea582%241%40news.povray.org%3E/
q) Listing this as an issue, but it's happening by original design and I'm
unsure what to do otherwise(*). The first character at x=0.0 gets special
treatment in that no extra left buffer is added as it is to characters with
x!=0.0. I think it was done this way to make it easier to position the start of
the string - and it does this. However, it also introduces an 'x' direction
discontinuity in placement which can show up if, for example, the user is
creating an animation using changes in the x value of the offset vector.
(*) Had the thought another keyword could be added to turn the special handling
on and off, but maybe being aware of the issue is enough for the users to avoid
it.
r) Font files contain mistakes! This is especially true for the huge number of
amateur created fonts which can be found on the web. Some of these are
auto-created by tracing someone's hand writing or drawings and the glyph
contours for these are often 'chaotic'.
Fonts are often rendered on the web by the FreeType library
(https://freetype.org/) its target output is creating (rasterized) glyph
images.
FreeType can handle badly implemented font packages much better than POV-Ray
because of the huge difference in development effort - and that it is often the
gate keeper / filter during a font's implementation. POV-Ray needs clean character
glyphs due the 3D extrusion more than if it were generating rasterized output.
All, a long winded way of saying a font which looks good on the web, might not
look good in POV-Ray. Professionally created fonts will likely be best on
average.
s) POV-Ray (yuqk) ships with the true type font files: crystal.ttf,
cyrvetic.ttf, povlogo.ttf and timrom.ttf. These are also available for package
installation with many linux distributions today. They are, as fonts, limited
overall - especially with respect to character support.
t) Jérôme Grimbert fixed long standing issues with cap normals during v3.8
development. Both v3.8 versions and so the yuqk fork will differ some from
earlier versions of POV-Ray with respect to top and bottom normals.
u) With orthogonal rays as when using an orthographic camera, where substantial
parts of a character's glyph runs horizontally or vertically there is an
exposure to position bias. The apparent 'width' of parts of the character can
change depending upon its position relative to the incoming rays.
With an orthographic camera this is due how the rendered pixels happen to align
with the underlying character glyph. The only solution / amelioration is to use
yuqk's +rdn / anti-alias_min_depth=n option, AA jitter - or to render larger
images which are later scaled down. This bias issue tangled in the hinting aspect of
font files not being supported by the POV-Ray code.
To a degree this position bias relative to incoming rays happens with objects
in general, but it's much more noticeable with text{} objects.
v) From work Christoph Lipka (clipka) did during v3.8 development that is still
present in POV-Ray's v4.0 master branch and the yuqk v3.8 based fork, there
exists a cmap{} sub feature for the text{} object which is only sort of
implemented. In limited testing it sometimes works and sometimes not, but it
could well be I'm not using it correctly too. The 'cmap{}' capability - or some
derivative form of it - likely of use. Further work is required. The feature is
not documented in the yuqk documentation.
References:
https://news.povray.org/povray.general/thread/%3C5c38071f%241%40news.povray.org%3E/
https://news.povray.org/povray.beta-test/thread/%3C5c323613%241%40news.povray.org%3E/
https://news.povray.org/povray.beta-test/thread/%3Cweb.5b1819544a827126535efa580%40news.povray.org%3E/
https://news.povray.org/povray.pov4.discussion.general/thread/%3C6427e66f%241%40news.povray.org%3E/
The yuqk fork state:
--------------------
'text' was modified.
Where useable:
--------------
Only within Scene Description Language (SDL) during parsing.
// SPDX-License-Identifier: CC-BY-SA-4.0