Skip to content

Commit 6c0d4aa

Browse files
Esteban82Esteban82
authored
Add tutorial about lines (#21)
1 parent 66c435f commit 6c0d4aa

File tree

2 files changed

+217
-0
lines changed

2 files changed

+217
-0
lines changed

‎docs/index.rst

+7
Original file line numberDiff line numberDiff line change
@@ -120,3 +120,10 @@ Basics
120120
:align: center
121121

122122
:doc:`tutorials/basics/color`
123+
124+
- .. image:: _images/ec0d8d5349173bd8da9d665f6f93ea70.png
125+
:target: tutorials/basics/line.html
126+
:width: 80%
127+
:align: center
128+
129+
:doc:`tutorials/basics/line`

‎docs/tutorials/basics/line.rst

+210
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
Setting attributes of lines
2+
---------------------------
3+
4+
In this tutorial we will show:
5+
6+
* `Use of lines`_
7+
* `Basic Attributes`_
8+
* `Examples of lines`_
9+
10+
Use of lines
11+
~~~~~~~~~~~~
12+
13+
In GMT, lines (also called *pen*) are used for many features, such as:
14+
15+
* Lines
16+
* Outlines of symbols
17+
* Borders of polygons
18+
* Outlines of text
19+
* Vectors (the line and the outline of the head)
20+
* Map frames
21+
* Scale bars
22+
23+
In the following example, all the colored elements are specified with the pen.
24+
25+
.. gmtplot::
26+
27+
gmt begin Pen_examples png
28+
# Basic frame map
29+
gmt basemap -R0/10/0/4 -Jx1c -B0 --MAP_FRAME_PEN=thin,mediumpurple
30+
# Scale bar
31+
gmt basemap -LjBR+w1c+jBR+l" cm"+o0.4c --MAP_TICK_PEN_PRIMARY=salmon
32+
# Create Line
33+
echo 1 1 > tmp
34+
echo 5 3 >> tmp
35+
echo 9 2 >> tmp
36+
# Plot line
37+
gmt plot tmp -Wthicker,red,...-
38+
# Plot symbol
39+
echo 4 1 | gmt plot -SA1c -W1p,orange
40+
# Plot text
41+
echo 2.2 3.5 "Hello GMT" | gmt text -Wthinner,darkblue,dotted -F+f24=thin,khaki1,solid -G211
42+
# Plot vector
43+
echo 6 1 25 2c | gmt plot -Sv0.3c+ea+p0.5p,deepskyblue -Wthin,darkgreen,--.
44+
gmt end
45+
46+
47+
Basic Attributes
48+
~~~~~~~~~~~~~~~~
49+
50+
The basic properties of a line are defined by a *pen*.
51+
It has three basic attributes:
52+
53+
* `Width`_
54+
* `Color`_
55+
* `Style`_
56+
57+
58+
Most programs will accept pen attributes in the form of an option argument, with commas separating the given attributes, e.g.,
59+
``width,color,style``.
60+
61+
**Default pen attributes**: By default they are 0.25-point wide, black and solid line.
62+
63+
Width
64+
=====
65+
66+
There are two ways to define the width:
67+
68+
**Note:** The width of a line will look bigger if the figure is enlarged (and vice versa).
69+
In this tutorial we add a graphic scale on the figures.
70+
71+
Custom
72+
++++++
73+
74+
Use a number to set the width. Append c, i, or p to specify pen width in cm, inch, or points, respectively.
75+
If not unit is append, them points is used as the unit. In GMT these units are related in this way:
76+
77+
1 inch = 2.54 cm = 72 points
78+
79+
80+
Pen names
81+
+++++++++
82+
83+
You can use one of the following preset names to define its width:
84+
85+
.. _tbl-pennames:
86+
87+
+----------+-------+----------+-------+---------+-----+
88+
| faint | 0 | thin | 0.75p | fat | 3p |
89+
+----------+-------+----------+-------+---------+-----+
90+
| default | 0.25p | thick | 1p | fatter | 6p |
91+
+----------+-------+----------+-------+---------+-----+
92+
| thinnest | 0.25p | thicker | 1.5p | fattest | 10p |
93+
+----------+-------+----------+-------+---------+-----+
94+
| thinner | 0.5p | thickest | 2p | wide | 18p |
95+
+----------+-------+----------+-------+---------+-----+
96+
97+
In the following example we show all the preset names (with differents colors).
98+
99+
**Note**: In the following examples the ``-Y`` parameter is only used to move the lines vertically. Otherwise the lines would be overlapped. It does not affect the line attributes.
100+
101+
.. gmtplot::
102+
103+
gmt begin lines_width png
104+
gmt basemap -R0/10/0/4 -Jx1c -B0 -LjBR+w1c+jBR+l" cm"+o0.4c
105+
echo 0.5 3.8 > tmp
106+
echo 8 3.8 >> tmp
107+
gmt plot tmp -Wfaint
108+
gmt plot tmp -Y-2p -Wthinnest,purple
109+
gmt plot tmp -Y-3p -Wthinner,blue
110+
gmt plot tmp -Y-4p -Wthin,green
111+
gmt plot tmp -Y-5p -Wthick,orange
112+
gmt plot tmp -Y-6p -Wthicker,red
113+
gmt plot tmp -Y-7p -Wthickest
114+
gmt plot tmp -Y-9p -Wfat,purple
115+
gmt plot tmp -Y-12p -Wfatter,blue
116+
gmt plot tmp -Y-15p -Wfattest,green
117+
gmt plot tmp -Y-20p -Wwide,orange
118+
gmt end
119+
120+
121+
Minimum-thickness pen
122+
+++++++++++++++++++++
123+
124+
This can be achieved by giving zero width (or faint).
125+
The result is device-dependent but typically means that as you zoom in on the feature in a display, the line thickness stays at the minimum.
126+
127+
128+
Color
129+
=====
130+
For the color, you can use all the methods explained in
131+
`How to use colors <https://www.generic-mapping-tools.org/gmt-examples/tutorials/basics/color.html>`_.
132+
133+
134+
Style
135+
=====
136+
137+
The style attribute controls the appearance of the line.
138+
By default all lines are drawn are solid.
139+
You can change this by using the following methods:
140+
141+
Names (or symbols)
142+
++++++++++++++++++
143+
144+
You can use some names to get following styles:
145+
146+
* dotted (or ".")
147+
* dashed (or "-")
148+
149+
Also combinations of dots and dashes, like ``.-`` for a dot-dashed line, are allowed.
150+
151+
152+
**Note**: The lengths of dots and dashes are scaled relative to the pen width
153+
(dots has a length that equals the pen width while dashes are 8 times as long; gaps between segments are 4 times the pen width).
154+
155+
156+
String
157+
++++++
158+
159+
For more detailed attributes (including exact dimensions) you may specify ``string[:offset]``. This is a series of numbers separated by underscores (_).
160+
These numbers represent a pattern by indicating the length of line segments and the gap between segments.
161+
The optional offset phase-shifts the pattern from the beginning the line.
162+
For example, if you want a thin line that alternates between long dashes (9 points), an 4 point gap, then a 3 point dash,
163+
then another 4 point gap, with pattern offset by 13 points from the origin, specify
164+
``-Wthin,9_4_3_4:13p``.
165+
Just as with pen width, the default style units are points, but can also be explicitly specified in cm, inch, or points (see width discussion above).
166+
167+
Here we show some examples of different style lines:
168+
169+
.. gmtplot::
170+
171+
gmt begin lines_style png
172+
gmt basemap -R0/10/0/2 -Jx1c -B0 -LjBR+w1c+jBR+l" cm"+o0.4c
173+
echo 0.5 1.8 > tmp
174+
echo 8 1.8 >> tmp
175+
gmt plot tmp -Wthin
176+
gmt plot tmp -Y-7p -Wthin,dotted
177+
gmt plot tmp -Y-7p -Wthin,dashed
178+
gmt plot tmp -Y-7p -Wthin,.-
179+
gmt plot tmp -Y-7p -Wthin,...-
180+
gmt plot tmp -Y-7p -Wthin,9_4_3_4
181+
gmt plot tmp -Y-7p -Wthin,9_4_3_4:13p
182+
gmt end
183+
184+
185+
Examples of lines
186+
~~~~~~~~~~~~~~~~~
187+
188+
Here we show some examples of lines combining the three basic attributes.
189+
190+
**Note**: In the last two examples the ``-Y`` parameter is NOT used so that the lines are intentionally overlapped to achieve more complex lines.
191+
192+
.. gmtplot::
193+
194+
gmt begin basic_lines png
195+
gmt basemap -R0/10/0/2 -Jx1c -B0 -LjBR+w1c+jBR+l" cm"+o0.4c
196+
echo 0.5 1.8 > tmp
197+
echo 8.0 1.8 >> tmp
198+
gmt plot tmp -W
199+
gmt plot tmp -Y-0.2c -W1p,red,-
200+
gmt plot tmp -Y-0.2c -W1p,blue,.
201+
gmt plot tmp -Y-0.2c -W1p,lightblue,-.
202+
gmt plot tmp -Y-0.2c -W2p,blue,..-
203+
gmt plot tmp -Y-0.2c -W2p,tomato,4_2:2p
204+
# Complex example of a 5p wide black line with a 2p wide red line above it
205+
gmt plot tmp -Y-0.3c -W5p,black
206+
gmt plot tmp -W2p,red
207+
# Complex example of 5p wide black line and 4p wide white dashed line on top of it
208+
gmt plot tmp -Y-0.3c -W5p,black
209+
gmt plot tmp -W4p,white,20p_20p
210+
gmt end

0 commit comments

Comments
 (0)