1mathsPIC(1) General Commands Manual mathsPIC(1)
2
6 mathsPIC
7
9 A. Syropoulos and R.W.D. Nickalls (April 26, 2010)
10 asyropoulos[at]<yahoo><com>
12 dick[at]<nickalls><org>
13
16 mathsPIC is a Perl filter program for PiCTeX. mathsPIC has its own
17 macro and macro library capability, and allows use of mathsPIC, PiCTeX,
18 TeX and LaTeX commands. A significant feature of mathsPIC is that it
19 allows access to the command-line, and so allows the user to extend
20 mathsPIC commands by calling Perl and other programs written to perform
21 particular drawing actions. See the package manual for full details and
22 examples. The latest version can be downloaded from
23 CTAN: tex-archive/graphics/pictex/mathspic/perl
25 Commands which can be used in the mathsPIC script file fall into four
27 main groups (a) mathsPIC macro commands (prefixed with %def), (b) regu‐
28 lar mathsPIC commands (do not have a backslash), (c) regular PiCTeX
29 commands (all have a backslash), and (d) regular TeX and LaTeX commands
30 (all have a backslash).
31 The following mathematics functions can used (note that decimal frac‐
33 tions having an absolute value less than 1 must have a leading zero).
34 Note also that all the trignometric functions require their argument in
35 radians.
36 Trigonometric: sin(), cos(), tan(), asin(), acos(), atan()
38 Remainder: rem(); eg var r=12 rem(5)
40 Integer: int(); eg var r= int(3.87) --> 3
42 Sign (returns -1, 0, +1): sgn(); eg var s=sgn(-3.27) --> -1
44 Square root: sqrt(); eg var s = sqrt(14)
46 Exponentiation: **; eg var j = r**2
48 Pi constant (3.14159...): _Pi_ and _pi_
50 e constant (2.71828...): _E_ and _e_
52 Linethickness: _linethickness_ ; eg var t = _linethickness_
54
57 perl mathspic.pl [-b] [-c] [-h] [-o <outfile>] <infile>
58 -b enables beep if mathsPIC detects an error
60 -c disables the writing of comments to output file
62 -h displays the help file
64 -o defines the output file name
66
68 macro definition commands are prefixed with %def and can take either
69 0, 1, or more parameters. Macros will generally be used as part of a
70 var command as shown below. Macros are deleted using the %undef com‐
71 mand.
72 -----syntax:
74 %def MACRONAME(parameters)<macrodefinition>
75 %undef MACRONAME(parameters)
76 -----notes:
78 Notes: (a) the () must be used in the definition even if no parameters
79 are used, (b) the name can be any combination of upper and lower case
80 characters and numbers, (c) when the macro is used in a command it is
81 prefixed by a & symbol, (d) it is a good idea to always place a % sym‐
82 bol at the end of the definition, (e) comments (prefixed by a % symbol)
83 can be placed after the macro definition just as in TeX or LaTeX.
84 -----examples:
86 %def d2r()_pi_/180% % degrees2radians
87 %def AreaOfRectangle(x,y)x*y% % width x, length y
88 %undef d2r() % delete the macro
89 -----use:
91 var j2= 6*(&d2r(45) + 23)
92 var a3 = 3*&AreaOfRectangle(5,7)
93
95 NUMERICAL EXPRESSIONS
96 When dealing with commands we will refer frequently to the term
97 `numerical expression' by which is meant either (a) a number (integer
98 or decimal), (b) a numeric variable or constant (defined using the var
99 or const command), (c) any mathsPIC function, macro, or mathematical
100 expression which evaluates to a number, or (d) a pair of point names
101 (e.g. AB) representing the Pythagorean distance between the two points.
102 A leading zero must be used with decimal fractions less than one.
103 In general, if a command's argument accepts a number then it will also
105 accept a `numerical expression' (<expr>) as defined above. Sometimes a
106 following <unit> is associated with the number or numerical expression,
107 in which case the number or numerical expression can be delimited by a
108 round bracket (or separated from the unit by a <space>), as shown in
109 the following examples.
110 -----examples:
112 ArrowShape(3mm, 20,40)
113 var h=4
114 ArrowShape(h mm, 20, 40)
115 ArrowShape((2*h)mm,20,40)
116 BACKSLASH \
119 A leading backslash without a following space indicates that it is
120 part of a PiCTeX, TeX or LaTeX command, in which case mathsPIC simply
121 copies the whole line verbatim into the output file. A leading back‐
122 slash followed by one or more spaces makes mathsPIC copy the whole line
123 verbatim into the output file but without the backslash.
124 USING THE COLOR PACKAGE
127 The standard COLOR package can be used with mathsPIC, but note that it
128 is important to load the COLOR package after the mathsPIC package.
129 It is best to place a comment symbol % at the end of LaTeX and TeX
131 commands to limit white space at the end.
132 In the event of any colour-spill from a diagram into any following
134 text (this used to be a problem in early TeX implementations) consider
135 using the \normalcolor command as a delimiter within the \beginpic‐
136 ture...\endpicture environment.
137 ==============================
139 ARROWSHAPE
141 This command defines the shape of an arrowhead, and allows different
142 arrowheads to be customised.
143 The default arrow shape is equivalent to the Arrowshape(2mm,30,40) com‐
145 mand. This default arrowhead shape can be reset using the Arrow‐
146 shape(default) command, as shown in the following example.
147 -----syntax:
149 arrowshape(<length>[units], <angledeg>, <angledeg>)
150 -----examples:
152 Arrowshape(4mm,30,60)
153 drawArrow(AB)
154 Arrowshape(default)
155 ==============================
157 beginLOOP...endLOOP
159 This is an environment which cycles a block of code a specified number
160 of times.
161 -----syntax:
163 beginLoop <expr>
164 ...
165 endLoop
166 -----notes:
168 The block of code which lies within the environment is input <expr>
169 times.
170 -----example:
172 beginLoop 5
173 ...
174 endLoop
175 ==============================
178 beginSKIP...endSKIP
180 This is an `environment' within which commands are not actioned. It is
181 useful in development for testing isolated commands and excluding other
182 commands.
183 ==============================
185 CONST
187 The const command is used to define scalar constants. Note that a
188 constant-name must begin with a single letter (either upper or lower
189 case), and may have up to a maximum of three following digits. Note
190 that constants, variables and points have the same name structure, and
191 a constant could have the same name as a point (and so we suggest
192 points have uppercase letters and variables and constants have lower‐
193 case letters). The scalar argument can be any numeric expression. New
194 values cannot be re-allocated to existing constant-names. If this
195 occurs mathsPIC will issue an error message.
196 -----syntax:
198 const name = <expr>
199 -----examples:
201 const r = 20, r4 = r3*tan(0.3)
202 ==============================
204 DashArray
206 The dasharray command takes an arbitrary number of paired arguments
207 that are used to specify a dash pattern.
208 -----syntax
210 dasharray(d1 , g1 , d2 , g2 , ... )
211 -----notes
213 The ds denotes the length of a dash and the gs denotes the length of
214 the gap between two consecutive dashes. There must be an even number of
215 arguments. If a variable or expression is used then it should be sepa‐
216 rated from the unit either by a <space> or with round brackets ( ) as
217 shown below.
218 -----example
220 dasharray(6pt, 2pt, 1pt, 2pt)
221 var d=2
222 dasharray(6pt, 2pt, 1pt, d pt)
223 dasharray(6pt, 2pt, 1pt, (d)pt)
224 dasharray(6pt, 2pt, 1pt, (3*d)pt)
225 ==============================
227 DrawAngleArc
229 This command draws an arc in the specified angle, a distance <radius>
230 from the angle. The angle is either <internal> (less than 180 deg) or
231 <external> (greater than 180 deg). The direction of the arc is either
232 <clockwise> or <anticlockwise>, and this direction must correspond with
233 the letter sequence specified for the angle. Strange and unexpected
234 results will be produced if the four parameters are not internally con‐
235 sistent. The option order angle/radius/internal or external/clockwise
236 or anticlockwise is important. The <radius> parameter can be any numer‐
237 ical expression.
238 -----syntax:
240 DrawAngleArc{angle(), radius(), external, clockwise}
241 -----example:
243 DrawAngleArc{angle(ABC), radius(3), external, clockwise}
244 var r=3
245 DrawAngleArc{angle(ABC), radius(r), external, clockwise}
246 ==============================
248 DrawAngleArrow
250 This command draws a curved arrow in the specified angle, a distance
251 <radius> from the angle. The angle is either <internal> (less than 180
252 deg) or <external> (greater than 180 deg). The direction of the arrow
253 is either <clockwise> or <anticlockwise>, and this direction must cor‐
254 respond with the letter sequence specified for the angle. Strange and
255 unexpected results will be produced if the four parameters are not
256 internally consistent. The option order angle/radius/internal/clockwise
257 is important. The <radius> parameter can be any numerical expression.
258 -----syntax:
260 DrawAngleArrow{angle(), radius(), external, clockwise}
261 -----example:
263 DrawAngleArrow{angle(ABC), radius(3), external, clockwise}
264 var r=3
265 DrawAngleArrow{angle(ABC), radius(r), external, clockwise}
266 ==============================
268 DrawArrow
270 This command draws an arrow(s) joining two points. The direction of
271 the arrow is in the point order specified.
272 -----syntax:
274 drawArrow(<line> [,<line>] ... )
275 -----notes:
277 The length option can only refer to one arrow
278 -----example:
280 drawArrow(AB)
281 drawArrow(FG, HJ)
282 ==============================
284 DrawCircle
286 This command draws a circle defined by its radius and the point-name
287 of its centre. The <radius> can be any numerical expression. If the
288 units of the X and Y axes are different, circles may be drawn
289 strangely, and mathsPIC therefore generates a warning message to this
290 effect.
291 -----syntax:
293 DrawCircle(<center>, <radius>)
294 -----examples:
296 drawCircle(C2,5)
297 drawCircle(C2,r2)
298 drawCircle(C2,r2/tan(1.3))
299 drawCircle(C2,AB)
300 ==============================
302 DrawCircumcircle
304 This command draws the circumcircle of a triangle.
305 -----syntax:
307 DrawCircumcircle(<triangle>)
308 -----example:
310 drawCircumcircle(ABC)
311 ==============================
313 DrawCurve
315 This command draws a smooth quadratic curve through three points in
316 the point order specified. Note that curves drawn using this command do
317 not break to avoid line-free zones associated with the points.
318 -----syntax:
320 DrawCurve(<point><point><point>)
321 -----example:
323 drawCurve(ABC)
324 ==============================
326 DrawExcircle
328 This command draws the excircle touching one side of a triangle.
329 -----syntax:
331 DrawExcircle(<triangle>, <side>)
332 -----example:
334 drawExcircle(ABC, BC)
335 ==============================
337 DrawIncircle
339 This command draws the incircle of a triangle.
340 -----syntax:
342 DrawIncircle(<triangle>)
343 -----example:
345 drawIncircle(ABC)
346 ==============================
348 DrawLine
350 This command draws a line joining two or more points. Use the
351 Linethickness command to vary thickness. This command uses the PiCTeX
352 \putrule command for horizontal and vertical lines, and the \plot com‐
353 mand for all other orientations.
354 -----syntax:
356 DrawLine( <points> [, <points>] )
357 -----notes:
359 <points> is any sequence of two or more point names.
360 <expr> is any numerical expression.
361 Lines are drawn in the order specified.
362 Lines are separated by a comma.
363 -----examples:
365 drawline(AB)
366 drawline(BCDE)
367 drawline(FG, HJK, PQRST)
368 ==============================
370 DrawPerpendicular
372 This command draws the perpendicular from a point to a line.
373 -----syntax:
375 DrawPerpendicular(<point>, <line)
376 -----example:
378 drawPerpendicular(P,AB)
379 ==============================
381 DrawPoint
383 This command draws the point-symbol at the point-location. Commas
384 must not be used to separate point names. The default point-symbol is
385 bullet unless an optional point-symbol (or string of characters) is
386 specified in the associated point command.
387 -----syntax:
389 DrawPoint(<point> [<point> ..])
390 -----examples:
392 drawpoint(T4)
393 drawpoint(ABCDEF)
394 drawpoint(P1 P2 P3 P4)
395 ==============================
397 DrawRightangle
399 This command draws the standard right-angle symbol in the internal
400 angle specified at the size specified by <expr>.
401 -----syntax:
403 DrawRightangle(<angle>, <expr>)
404 -----notes:
406 The <expr> can be any numerical expression.
407 -----example:
409 drawRightangle(ABC,3)
410 drawRightangle(ABC,PQ)
411 var d=5
412 drawRightangle(ABC,d)
413 ==============================
415 DrawSquare
417 This command draws a square defined by its side and the point-name of
418 its centre. The <sidelength> can be any numerical expression.
419 -----syntax:
421 DrawSquare(<centerpoint>, <sidelength>)
422 -----examples:
424 drawSquare(P,5)
425 var s2=3, j=2
426 drawSquare(P,s2)
427 drawSquare(P, s2*4/(3*j))
428 drawSquare(P,AB)
429 ==============================
431 DrawThickArrow
433 This command draws a thick arrow(s) joining two points. The direction
434 of the arrow is in the point order specified. The shape of the arrow‐
435 head is controlled by the ArrowShape command.
436 -----syntax:
438 drawThickArrow(<line> [,<line>,...])
439 -----examples:
441 drawThickarrow(BC)
442 drawThickarrow(PQ, RS)
443 ==============================
445 DrawThickLine
447 This command draws a thick line(s) joining two points. The direction
448 of the line is in the point order specified. Use the Linethickness com‐
449 mand to vary thickness of a line.
450 -----syntax:
452 drawThickLine(<line> [,<line>,...])
453 -----examples:
455 drawThickline(BC)
456 drawThickline(PQ, RS)
457 ==============================
459 InputFile
461 This command inputs a plain text file containing mathsPIC commands.
462 Optionally, the file can be input several times, in which case this
463 command functions like a DO--LOOP. The <loopnumber> can be any numeri‐
464 cal expression. If the <loopnumber> is not an integer then mathsPIC
465 will round the value down to the nearest integer. See also the begin‐
466 LOOP ... endLOOP commands.
467 -----syntax:
469 inputFile[*](<filename>)[<loopnumber>]
470 -----notes:
472 The inputfile* command is used to input a file in verbatim, i.e. a
473 file with no mathsPIC commands, for example, a file containing only
474 PiCTeX commands or data-points for plotting etc. Note that the input‐
475 file* command has no <loopnumber> option. Note also that PiCTeX
476 requires a ODD number of points.
477 -----examples:
479 inputFile(myfile.dat)[4]
480 inputFile*(mycurvedata.dat)
481 ==============================
483 LineThickness
485 This command sets a particular linethickness. The command linethick‐
486 ness(default) restores the working linethickness to the default value
487 of 0.4pt. The current value of the linethickness (in current units)
488 can be accessed using the var command (this can be useful when drawing
489 figures using thick lines) .
490 -----syntax:
492 LineThickness(<expr><units>)
493 LineThickness(default)
494 var t = _linethickness_
495 -----notes:
497 This command also sets the font to cmr and plotsymbol to \CM . and
498 also sets the rule thickness for drawing horizontal and vertical lines.
499 It is important to include a leading zero with decimal fractions less
500 than one.
501 -----examples:
503 linethickness(2pt)
504 var t=3
505 linethickness((t)pt)
506 lineThickness((2*t)pt)
507 linethickness(default)
508 var t = _linethickness_
509 -----caution:
511 Note that there is a similar PiCTeX command with the same name (but
512 with a different syntax).
513 ==============================
515 PAPER
517 Defines the plotting area in terms of the options units(), xrange(),
518 yrange(), axes(), and ticks(). The units() argument must contain a
519 numeric value and a valid TeX length unit mm, cm, pt, pc(pica),
520 in(inch), bp(big point), dd(didot), cc(cicero), sp(scaled point). The X
521 and Y axes can have different units (see second example below). The
522 axes() arguments XYTBLR refer to the X and Y axes, and the Top, Bot‐
523 tom, Left and Right axes. A * following one of the axes disables ticks
524 on that axis. The X and Y axes pass through the zeros.
525 -----examples:
527 paper{units(1cm),xrange(0,10),yrange(0,10)}
528 paper{units(2cm,1cm),xrange(0,10),yrange(0,10),axes(LB)}
529 paper{units(1mm),xrange(0,100),yrange(0,100),axes(XY)}
530 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRTBXY),ticks(1,1)}
531 paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRT*B*)}
532 ==============================
534 POINT
536 Defines a new point by allocating coordinates to a new point name. The
537 * option re-allocates coordinates to an existing point name.
538 -----syntax:
540 POINT[*](<name>){<point>}[symbol=<chars>, radius=<expr>]
541 POINT[*](<name>){<location>}[symbol=<chars>, radius=<expr>]
542 -----notes:
544 <name> one leading letter plus maximum of three trailing digits
545 <chars> any TeX string allowed in an \hbox{}
546 <expr> any numerical expression
547 The polar(r,theta) option defaults to radians for the angle theta. To
548 work in degrees then must append <deg> eg: polar(r,theta deg). Can use
549 <direction()> and <directiondeg()> to replace theta. Note that the term
550 vector(AB) means use same (r, theta) as AB.
551 -----examples:
553 point(A){5,5}
554 point(B2){22,46}[symbol=$\odot$]
555 point(B2){22,46}[symbol=circle(2),radius=5]
556 var r=3
557 point(B2){22,46}[symbol=square(3),radius=r]
558 point(B123){22,46}[radius=5]
559 point(D2){B2, shift(5,5)}
560 var s = 3
561 point(D2){B2, shift(2*s,4*s)}
562 point(D3){D2, polar(6,32 deg)}
563 point(D4){D2, polar(6,1.2 rad)}
564 point(D4){D2, polar(6, direction(AB))} %% radians by default
565 point(D4){D2, polar(6, directiondeg(AB) deg)}
566 point(G2){Q, rotate(P, 23 deg)}
567 point(G2){Q, vector(AB)}
568 point(D2){intersection(AB,CD)}
569 point(F){PointOnLine(AB,5.3)}
570 point(G){perpendicular(P,AB)}
571 point(H){circumcircleCenter(ABC)}
572 point(J){incircleCenter(ABC)}
573 point(K){excircleCenter(ABC,BC)}
574 point*(A){6,3}
575 point*(P){Q}
576 point*(B){B, shift(5,0)}
577 point*(P){xcoord(J),ycoord(K)}
578 ==============================
580 PointSymbol
582 This command allows the default point-symbol \bullet (with zero line-
583 free radius) to be changed. The PointSymbol command is particularly
584 useful where a set of points uses the same point-symbol, for example,
585 when drawing graphs. The point-symbol can be reset to the default \bul‐
586 let using the command PointSymbol(default).
587 -----syntax:
589 PointSymbol(<symbol>, <line-free-radius>)
590 PointSymbol(default)
591 -----notes:
593 The PointSymbol command only influences subsequent point commands.
594 The optional square bracket of the point command overrides the
595 PointSymbol command.
596 -----examples:
598 PointSymbol($\odot$, 0.7)
599 PointSymbol(default)
600 ==============================
602 SYSTEM
604 This command allows the user to access the command line and execute
605 standard Linux commands. A important use for this command is to run a
606 Perl program.
607 -----syntax:
609 System("<command>")
610 -----notes:
612 The <command> string must be in inverted commas.
613 -----example:
615 system("dir > mydir-listing.txt")
616 system("perl myperlprogram.pl")
617 ==============================
619 SHOW....
621 This command makes mathsPIC return the value of a calculation or spec‐
622 ified parameter; for example, the value of a particular angle, or the
623 length of a line. The result is shown in the output-file as a commented
624 line. This allows mathsPIC commands to be adjusted in the light of
625 calculations. There are currently five such commands as follows.
626 -----syntax:
628 showLength(AB)
629 showAngle(ABC) % returns angle in radians
630 showAngledeg(ABC) % returns angle in degrees
631 showArea(ABC)
632 showPoints
633 showVariables
634 ==============================
636 TEXT
638 This command places a text-string at a specific location. By default
639 the text is centered vertically and horizontally at the specified
640 point. Optionally, text can be placed relative to a point using appro‐
641 priate combinations of the PiCTeX `position' options l t r B b to
642 align the (l)eft edge, (r)ight edge, (t)op edge, (B)aseline, (b)ottom
643 edge respectively of the text box with the point-location.
644 Remember that the default units for the angle argument of the polar()
646 expression is radians; hence you MUST append `deg' if you want to work
647 in degrees
648 -----syntax:
650 text(<string>){<location>}[<position options>]
651 text(<string>){<pointname>, shift(<x>,<y>)}[]
652 text(<string>){<pointname>, polar(<r>,<angle>[rad])}[]
653 -----examples:
655 text(A){5,6}
656 text($A_1$){A1, shift(2, 2)}
657 text(Z2){Z2, shift(5, -5)}[tr]
658 text(Z3){Z2, polar(5, 20 deg)}[Br]
659 text(Z4){Z2, polar(5, 1.34 rad)}
660 text(\framebox{Z5}){Z5}
661 ==============================
663 VAR
665 The var command is used to define scalar variables. It can be any
666 numerical expression. A variable-name must begin with a single letter
667 (either upper or lower case), and may have up to a maximum of four fol‐
668 lowing digits. If a more detailed variable name is required, then a
669 simple alternative is to use a mathsPIC macro---as any string can be
670 allocated via macros (see the beginning of this chapter for details on
671 macros).
672 Note that variables, constants and points have the same name struc‐
674 ture, and a variable can have the same name as a point (and so we sug‐
675 gest points have uppercase letters and variables and constants have
676 lowercase letters). New values can be re-allocated to existing vari‐
677 able-names; however, when this occurs then mathsPIC does not issue a
678 warning message to hightlight this fact.
679 If it is important to be warned if a potential variable is acciden‐
681 tally reallocated then one should consider using the const command
682 instead (since mathsPIC does generate an error message if a constant is
683 reallocated).
684 -----syntax:
686 var <name> = <expr>
687 -----notes:
689 In addition to the mathematical functions mathsPIC functions which can
690 be used with the var command are:
691 angle(<three-points>) % returns angle in radians
693 angledeg(<three-points>) % returns angle in degrees
694 area(<three-points>)
695 xcoord(<point>)
696 ycoord(<point>)
697 direction(<two-points>) % returns angular direction in radians
698 directiondeg(<two-points>) % returns angular direction in degrees
699 -----examples:
701 var r = 20, r4 = r3*tan(0.3), j = (r*2e3)**2, r5 = AB
702 var e = _e_, p1 = _Pi_
703 var t = _linethickness_ % returns linethickness in current units
704 var g137 = angle(ABC) %(default: returns in radians)
705 var g = angledeg(ABC) % angle in degrees
706 var h = area(ABC)
707 var x2 = xcoord(A), y2 = ycoord(A)
708 var m5 = 12 rem 3 % remainder after dividing by 3
709 var r1 = direction(PQ) % in radians
710 var d1 = directiondeg(PQ)
711 ==============================
713
715 The mathsPIC package manual and examples
716
718 Please report bugs to Dick Nickalls (dick [AT] nickalls [dot] org) or
719 to Apostolos Syropoulos
720mathsPIC perl version April 26, 2010 mathsPIC(1)