VCS Text Objects

Table Of Content

Introduction

VCS let you plot text objects on a plot.

[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]

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

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:

[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

[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

[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)
[5]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_9_0.png

Example:

[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
[6]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_11_1.png

Adding fonts

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

[7]:
canvas.clear()
vcs.addfont("FFF_Tusj.ttf", name="Myfont")
txt.font = "Myfont"
canvas.plot(txt)
[7]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_13_0.png

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

[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)
[8]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_15_0.png

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.

[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), \
[9]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_17_1.png

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.

[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:

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

Angle

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

[12]:
canvas.clear()
txt.angle = 45
txt.height =20.
txt.string = "A Rotated Text"
canvas.plot(txt)
[12]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_23_0.png

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)

[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)
[13]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_25_0.png

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

[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)
[14]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_27_0.png

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.

[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)
[15]:
../../../_images/API_graphics_Jupyter_VCS_Text_Objects_29_0.png
[ ]: