# VCS_Text_Objects Tutorial [download iPython Notebook](VCS_Text_Objects.ipynb) VCS_Text_Objects
In [1]:
# Styling for notebook
from __future__ import print_function
from IPython.core.display import HTML
HTML("""
<style>
.output_png {
    display: table-cell;
    text-align: center;
    vertical-align: middle;
}
</style>
""")
import vcs
canvas=vcs.init(geometry=(800,600),bg=True)
txt = vcs.createtext()
txt.list()
---------- Text combined (Tc) member (attribute) listings ----------
secondary method = Tc
 ---------- Text Table (Tt) member (attribute) listings ----------
Tt_name = __texttable_365611846777884
font = 1
spacing = 2
expansion = 100
color = [0.0, 0.0, 0.0, 100.0]
fillincolor = 0
priority = 1
string = ['']
viewport = [0.0, 1.0, 0.0, 1.0]
worldcoordinate = [0.0, 1.0, 0.0, 1.0]
x = None
y = None
projection = default
 ---------- Text Orientation (To) member (attribute) listings ----------
To_name = __textorientation_116900871963565
height = 14
angle = 0
path = right
halign = left
valign = half

As you can see VCS text pbjects are composed of two part the texttable and the textorientation

Text Table controls the font, color, actual text (string), and location options Text Orientation control the text font, size and alignements

Controling Placements of Text Objects

Please refer to the VCS Principles for details on viewport and worldcoordinates.

Essentially the viewport describe the area on the canvas where to draw, and the world coordinates are used within this area. Both are initialized at [0,1,0,1]

In [2]:
txt.string = 'Hello VCS User'  # Or list of strings
txt.x = .5  # Or list of coordinates
txt.y = .5
canvas.plot(txt)
Out[2]:

Text Table

Fonts

Changing the font

You can control the fonts via the font attribute

Available fonts a are available via the vcs.getlistelements("font") option

Default fonts are:

In [3]:
print(vcs.listelements("font"))
['Adelon', 'Arabic', 'AvantGarde', 'Chinese', 'Clarendon', 'Courier', 'DejaVuSans', 'DejaVuSans-Bold', 'DejaVuSans-BoldOblique', 'DejaVuSans-ExtraLight', 'DejaVuSans-Oblique', 'DejaVuSansCondensed', 'DejaVuSansCondensed-Bold', 'DejaVuSansCondensed-BoldOblique', 'DejaVuSansCondensed-Oblique', 'Greek', 'Hebrew', 'Helvetica', 'Maths1', 'Maths2', 'Maths3', 'Maths4', 'Russian', 'Times', 'default']

You can also access font by their number, you can get a font name based on its number or vice-versa get a font number based on its name

In [4]:
print("The 'Times' font number is:",vcs.getfontnumber("Times"))
print("The name of number 5 is:", vcs.getfont(5))
The 'Times' font number is: 6
The name of number 5 is: Adelon

Default font

If you wish to change vcs default font (will affect every object using font 1) you can use setdefaultfont

In [5]:
canvas.clear()
t = canvas.createtext()
t.string = "Default as default font"
t.x = .3
t.halign = "center"
t.y = .5
canvas.plot(t)
vcs.setdefaultfont("DejaVuSans-Bold")
t = canvas.createtext()
t.string = "DejaVuSans-Bold as default font"
t.x = .7
t.halign = "center"
t.y = .5
canvas.plot(t)
Out[5]:

Example:

In [6]:
# rest to default font: AvantGarde
vcs.setdefaultfont("AvantGarde")
fonts = vcs.listelements("font")
N = len(fonts)
grid = 5. # 5x5 grid
delta = 1./6.
canvas.clear()
for i, font in enumerate(fonts):
    print("I,f:",i,font)
    txt.font = font
    txt.string = font
    yindx = i % grid
    xindx = int(i/grid)
    txt.x = delta + xindx*delta
    txt.y = delta + yindx*delta
    dsp = canvas.plot(txt)
# Resets
txt.x = [.5]
txt.y = [.5]
txt.string = "A VCS Text Object"
dsp
I,f: 0 Adelon
I,f: 1 Arabic
I,f: 2 AvantGarde
I,f: 3 Chinese
I,f: 4 Clarendon
I,f: 5 Courier
I,f: 6 DejaVuSans
I,f: 7 DejaVuSans-Bold
I,f: 8 DejaVuSans-BoldOblique
I,f: 9 DejaVuSans-ExtraLight
I,f: 10 DejaVuSans-Oblique
I,f: 11 DejaVuSansCondensed
I,f: 12 DejaVuSansCondensed-Bold
I,f: 13 DejaVuSansCondensed-BoldOblique
I,f: 14 DejaVuSansCondensed-Oblique
I,f: 15 Greek
I,f: 16 Hebrew
I,f: 17 Helvetica
I,f: 18 Maths1
I,f: 19 Maths2
I,f: 20 Maths3
I,f: 21 Maths4
I,f: 22 Russian
I,f: 23 Times
I,f: 24 default
Out[6]:

Adding fonts

You can add TrueType fonts to vcs by using the canvas.addfont function

In [7]:
canvas.clear()
vcs.addfont("FFF_Tusj.ttf", name="Myfont")
txt.font = "Myfont"
canvas.plot(txt)
Out[7]:

Color

You can control the font color via the color attribute, you can send a string representing the color name, an index in the text object colormap.

You can change the colormap via the colormap attribute

In [8]:
canvas.clear()
txt.font = "default"
txt.color = "Red"
canvas.plot(txt)
txt.x[0] += .2
txt.color = 5
canvas.plot(txt)
txt.colormap = "AMIP"  # Changing the colormap chjange the color of index 5
txt.x[0] -= .4
canvas.plot(txt)
Out[8]:

Projection

IF your worldcoordinates are representing lat/lon, you can use the projection attribute to apply a projection (and its settings) to your text location.

In [9]:
canvas.clear()
import cdms2, os
f=cdms2.open(os.path.join(vcs.sample_data,"clt.nc"))
bot = canvas.gettemplate("bot_of2")
top = canvas.gettemplate("top_of2")
gm = canvas.createisoline()
gm.datawc_x1 = -180
gm.datawc_x2 = 180
gm.datawc_y1 = -90
gm.datawc_y2 = 90
canvas.plot(f("clt", slice(0,1)),gm,top)
proj = "polar"
gm.projection = proj
canvas.plot(f("clt",slice(0,1),longitude=(-180,181)),gm,bot)
txt = canvas.createtext()
txt.string = "Non proj"
txt.worldcoordinate = [-180,180,-90,90]
txt.x = -30
txt.y = 80
txt.color="blue"
txt.height = 15
txt.halign = "center"
txt.viewport = top.data.x1, top.data.x2, top.data.y1, top.data.y2
canvas.plot(txt)
txt.projection = proj
txt.color = "red"
txt.string = "PROJECTED"
txt.viewport = bot.data.x1, bot.data.x2, bot.data.y1, bot.data.y2
canvas.plot(txt)# canvas.plot(txt)
/Users/doutriaux1/anaconda2/envs/cdat8/lib/python2.7/site-packages/vtk/util/numpy_support.py:135: FutureWarning: Conversion of the second argument of issubdtype from `complex` to `np.complexfloating` is deprecated. In future, it will be treated as `np.complex128 == np.dtype(complex).type`.
  assert not numpy.issubdtype(z.dtype, complex), \
Out[9]:

Ordering in the plot

you can control the layer on which the object will be drawn via the priority attribute. Higher priority object are drawn on top of lower priority ones.

In [10]:
txt.priority = 0  # Turn off
txt.priority = 2  # move to a layer on top of "default" layer (1)

Deprecated attributes

The following attribute are left over from XGKS and are not use anymore:

spacing, fillingcolor, expansion

Text Orientation

Size

You can control the size (or height) of text objects as follow:

In [11]:
canvas.clear()
txt = vcs.createtext()
txt.string = "Example of BIG Text"
txt.x = .5
txt.y = .5
txt.height = 30
canvas.plot(txt)
Out[11]:

Angle

You can control the clockwise rotation of a text object as shown bellow:

In [12]:
canvas.clear()
txt.angle = 45 
txt.height =20.
txt.string = "A Rotated Text"
canvas.plot(txt)
Out[12]:

Alignement

You can control how to align the text relatively to to its coordinates

Horizontal Alignement

You can control the horizontal alignement via the halign attribute, possible values are: ('left', 'center', 'right') or (0, 1, 2)

In [13]:
canvas.clear()
line = vcs.createline()
line.x = [.5,.5]
line.y = [0.,1.]
line.type ="dot"
line.color=["grey"]
center = vcs.createtext()
center.x = .5
center.y = .5
center.string = "Centered Text"
center.halign = "center"
right = vcs.createtext()
right.x = .5
right.y = .25
right.string = "Right Aligned Text"
right.halign = "right"
left = vcs.createtext()
left.x = .5
left.y = .75
left.string = "Left Aligned Text"
left.halign = "left"
canvas.plot(center)
canvas.plot(right)
canvas.plot(left)
canvas.plot(line)
Out[13]:

Vertical Alignement

You can control the vertical alignement via the valign attribute, possible values are: ('top', 'cap', 'half', 'base', 'bottom') or (0, 1, 2, 3, 4)

Note that cap is the same as top at the moment

In [14]:
canvas.clear()
line = vcs.createline()
line.y = [.5,.5]
line.x = [0.,1.]
line.type ="dot"
line.color=["grey"]
half = vcs.createtext()
half.height = 20
half.halign = "center"
half.x = .5
half.y = .5
half.string = "Half Aligned Text"
half.valign = "Half"
bottom = vcs.createtext()
bottom.halign='center'
bottom.height=20
bottom.x = .25
bottom.y = .5
bottom.string = "Bottom Aligned Text"
bottom.valign = "bottom"
top = vcs.createtext()
top.halign='center'
top.height=20
top.x = .75
top.y = .5
top.string = "Top Aligned Text"
top.valign = "top"
cap = vcs.createtext()
cap.x = .75
cap.y = .75
cap.string = "Cap Aligned Text"
cap.valign = "cap"
canvas.plot(half)
canvas.plot(bottom)
canvas.plot(top)
canvas.plot(line)
Out[14]:

Mathematical Expressions and Symbols

See dedicated notebook

Example: Bringing it all together

We are plotting a world coordinate locate rotated and colored text object on top of a map.

In [15]:
canvas.clear()
import cdms2, os
f=cdms2.open(os.path.join(vcs.sample_data,"clt.nc"))

# Continental U.S.A. region
lat1 = 15.
lat2 = 70.
lon1 = -140.
lon2 = -60.
proj = "lambert"

# Read data in
clt = f("clt",time=slice(0,1),latitude=(lat1,lat2),longitude=(lon1,lon2),squeeze=1)

# Isofill method
gm = vcs.createisofill()
gm.datawc_x1 = lon1
gm.datawc_x2 = lon2
gm.datawc_y1 = lat1
gm.datawc_y2 = lat2
gm.projection = proj

# Template (not modified)
templ = vcs.createtemplate()

# Text object
txt = vcs.createtext()
txt.string = ["Washington D.C.", "New York", "Los Angeles"]
txt.halign = "center"
txt.valign = "half"
txt.color = "red"
txt.font = "Myfont"
txt.height = 15
txt.priority = 2
txt.angle = -5
txt.y = [38.9072, 40.7128, 34.0522]
txt.x = [-77.0369, -74.0060, -118.2437]
txt.worldcoordinate = [lon1, lon2, lat1, lat2]
txt.viewport = [templ.data.x1, templ.data.x2, templ.data.y1, templ.data.y2]
txt.projection = proj

# Plot text first to show priority
canvas.plot(txt)

# Now data plotted "bellow" text
canvas.plot(clt,gm)
Out[15]: