mathsPIC(1)

✨ mathsPIC ✨

Manual section 1 from the General Commands Manual, bestie 🎀

💖 NAME

mathsPIC

👑 AUTHORS

A. Syropoulos and R.W.D. Nickalls (April 26, 2010) 🫶

asyropoulos[at]<yahoo><com> dick[at]<nickalls><org>

🌸 DESCRIPTION

okay so mathsPIC is a Perl filter program for PiCTeX, and it's giving main character energy 💅. It has its own macro and macro library capability, and it lets you use mathsPIC, PiCTeX, TeX, and LaTeX commands all together. The highlight is that it can reach the command line, so you can extend mathsPIC by calling Perl and other programs written for particular drawing actions ✨. For full details and examples, check the package manual. The latest version can be downloaded from:

CTAN: tex-archive/graphics/pictex/mathspic/perl

Commands you can use in a mathsPIC script file come in four main groups 🦋:

• (a) mathsPIC macro commands (prefixed with %def)
• (b) regular mathsPIC commands (no backslash)
• (c) regular PiCTeX commands (all have a backslash)
• (d) regular TeX and LaTeX commands (all have a backslash)

Now the math bit 🧚. These functions are available, but remember that decimal fractions with an absolute value less than 1 must have a leading zero, and all the trigonometric functions want their argument in radians 📐.

• Trigonometric: sin(), cos(), tan(), asin(), acos(), atan()
• Remainder: rem(); eg var r=12 rem(5)
• Integer: int(); eg var r= int(3.87) --> 3
• Sign (returns -1, 0, +1): sgn(); eg var s=sgn(-3.27) --> -1
• Square root: sqrt(); eg var s = sqrt(14)
• Exponentiation: **; eg var j = r**2
• Pi constant (3.14159...): _Pi_ and _pi_
• e constant (2.71828...): _E_ and _e_
• Linethickness: _linethickness_; eg var t = _linethickness_

🎀 COMMAND-LINE USE

Run it like this:

perl mathspic.pl [-b] [-c] [-h] [-o  <outfile>]  <infile>

• -b — beeps if mathsPIC spots an error 🔔
• -c — turns off writing comments to the output file 🙈
• -h — pulls up the help file 🆘
• -o — sets the output file name 📁

🦋 MACRO COMMANDS

Macro definition commands are prefixed with %def, and they can take 0, 1, or more parameters. Macros usually show up as part of a var command, and you delete them with the %undef command 🗑️.

Syntax:

%def MACRONAME(parameters)<macrodefinition>
%undef MACRONAME(parameters)

Notes:

• (a) you must use () in the definition even if there are no parameters, bestie
• (b) the name can be any mix of upper and lower case characters and numbers
• (c) when you use the macro in a command, prefix it with a & symbol
• (d) it's a good idea to always put a % symbol at the end of the definition
• (e) comments (prefixed by a % symbol) can go after the macro definition, just like in TeX or LaTeX 💜

Examples:

%def d2r()_pi_/180%              % degrees2radians
%def AreaOfRectangle(x,y)x*y%    % width x, length y
%undef d2r()                     % delete the macro

Use:

var j2= 6*(&d2r(45) + 23)
var a3 = 3*&AreaOfRectangle(5,7)

🌈 GENERAL COMMANDS

🔢 NUMERICAL EXPRESSIONS

When we talk about a numerical expression in commands, we mean any of these 🍓:

• (a) a number (integer or decimal)
• (b) a numeric variable or constant (defined with the var or const command)
• (c) any mathsPIC function, macro, or mathematical expression that evaluates to a number
• (d) a pair of point names (e.g. AB) representing the Pythagorean distance between the two points

Decimal fractions less than one need a leading zero, no exceptions 🙅‍♀️.

If a command's argument accepts a number, it'll also accept a numerical expression (<expr>) as defined above. Sometimes a following <unit> goes with the number or expression, and then you can wrap the number or expression in round brackets (or separate it from the unit with a <space>). Check these out:

Examples:

ArrowShape(3mm, 20,40)
var h=4
ArrowShape(h mm, 20, 40)
ArrowShape((2*h)mm,20,40)

🔙 BACKSLASH \

A leading backslash with no space right after it means the line is part of a PiCTeX, TeX, or LaTeX command. In that case mathsPIC just copies the whole line verbatim into the output file 📋. A leading backslash followed by one or more spaces also makes mathsPIC copy the whole line verbatim, but this time the backslash gets dropped 🫧.

🎨 USING THE COLOR PACKAGE

The standard COLOR package works with mathsPIC, but it's important to load the COLOR package after the mathsPIC package 🖌️.

It's best to put a comment symbol % at the end of LaTeX and TeX commands so you don't pick up extra white space at the end ✂️.

If colour spills from a diagram into the text that follows (this used to be a problem in early TeX implementations), try using the \normalcolor command as a delimiter inside the \beginpicture...\endpicture environment 🚨.

💀 Heads up: colour-spill is the kind of thing that sneaks up on you, so keep an eye out for it.

==============================

🏹 ARROWSHAPE

This command defines the shape of an arrowhead, and it lets you customise different arrowheads 🏹✨.

The default arrow shape is equivalent to Arrowshape(2mm,30,40). You can reset this default arrowhead shape with Arrowshape(default), as in the example below 🔄.

Syntax:

arrowshape(<length>[units], <angledeg>, <angledeg>)

Examples:

Arrowshape(4mm,30,60)
drawArrow(AB)
Arrowshape(default)

==============================

🔁 beginLOOP...endLOOP

This is an environment that cycles a block of code a specified number of times 🔁💕.

Syntax:

beginLoop <expr>
...
endLoop

Notes:

The block of code inside the environment is run <expr> times.

Example:

beginLoop 5
...
endLoop

==============================

🚫 beginSKIP...endSKIP

This is an environment where commands are not actioned. It's handy in development for testing isolated commands while leaving everything else out 🙈.

==============================

📦 CONST

The const command defines scalar constants 📦. A constant-name must start with a single letter (upper or lower case), and it can have up to three digits after that. Constants, variables, and points all share the same name structure, so a constant could have the same name as a point. That's why we suggest points use uppercase letters and variables and constants use lowercase letters 🔤. The scalar argument can be any numeric expression.

⚠️ You can't re-allocate new values to existing constant-names. If you try, mathsPIC will throw an error message at you 😭.

Syntax:

const name = <expr>

Examples:

const r = 20, r4 = r3*tan(0.3)

==============================

🪡 DashArray

The dasharray command takes an arbitrary number of paired arguments that make up a dash pattern 🪡.

Syntax:

dasharray(d1 , g1 , d2 , g2 , ... )

Notes:

The ds are the lengths of the dashes, and the gs are the lengths of the gaps between two consecutive dashes. You need an even number of arguments 🔢. If you use a variable or expression, separate it from the unit with either a <space> or round brackets ( ), as shown below.

Example:

dasharray(6pt, 2pt, 1pt, 2pt)
var d=2
dasharray(6pt, 2pt, 1pt, d pt)
dasharray(6pt, 2pt, 1pt, (d)pt)
dasharray(6pt, 2pt, 1pt, (3*d)pt)

==============================

🌙 DrawAngleArc

This command draws an arc in the specified angle, at a distance <radius> from the angle 🌙. The angle is either <internal> (less than 180 deg) or <external> (greater than 180 deg). The arc's direction is either <clockwise> or <anticlockwise>, and that direction has to match the letter sequence you gave for the angle 🔄. The option order (angle/radius/internal or external/clockwise or anticlockwise) matters too. The <radius> parameter can be any numerical expression.

💀 If the four parameters aren't internally consistent, you'll get strange and unexpected results. Be careful, bestie!

Syntax:

DrawAngleArc{angle(), radius(), external, clockwise}

Example:

DrawAngleArc{angle(ABC), radius(3), external, clockwise}
var r=3
DrawAngleArc{angle(ABC), radius(r), external, clockwise}

==============================

🏹 DrawAngleArrow

This command draws a curved arrow in the specified angle, at a distance <radius> from the angle 🏹. The angle is either <internal> (less than 180 deg) or <external> (greater than 180 deg). The arrow's direction is either <clockwise> or <anticlockwise>, and that direction has to match the letter sequence you gave for the angle 🔄. The option order (angle/radius/internal/clockwise) is important. The <radius> parameter can be any numerical expression.

💀 Same warning as always: if the four parameters aren't internally consistent, you'll get strange and unexpected results.

Syntax:

DrawAngleArrow{angle(), radius(), external, clockwise}

Example:

DrawAngleArrow{angle(ABC), radius(3), external, clockwise}
var r=3
DrawAngleArrow{angle(ABC), radius(r), external, clockwise}

==============================

➡️ DrawArrow

This command draws one or more arrows joining two points 🫶. The arrow points in the order you specify the points 👉.

Syntax:

drawArrow(<line> [,<line>] ... )

Notes:

The length option can only refer to one arrow 📏.

Examples:

drawArrow(AB)
drawArrow(FG, HJ)

==============================

⭕ DrawCircle

This command draws a circle using its radius and the point-name of its centre ⭕. The <radius> can be any numerical expression. If the units on the X and Y axes are different, circles can come out looking weird, so mathsPIC generates a warning message to let you know 🚨.

Syntax:

DrawCircle(<center>, <radius>)

Examples:

drawCircle(C2,5)
drawCircle(C2,r2)
drawCircle(C2,r2/tan(1.3))
drawCircle(C2,AB)

==============================

🔺 DrawCircumcircle

This command draws the circumcircle of a triangle 🔺.

Syntax:

DrawCircumcircle(<triangle>)

Example:

drawCircumcircle(ABC)

==============================

🌷 DrawCurve

This command draws a smooth quadratic curve through three points, in the point order you specify 🌷. Curves drawn with this command don't break to avoid line-free zones around the points, so keep that in mind 🫧.

Syntax:

DrawCurve(<point><point><point>)

Example:

drawCurve(ABC)

==============================

🌕 DrawExcircle

This command draws the excircle that touches one side of a triangle 🌕.

Syntax:

DrawExcircle(<triangle>, <side>)

Example:

drawExcircle(ABC, BC)

💖 DrawIncircle 💖

okay so this one draws the incircle of a triangle 🦋 super clean, no notes, no fuss ✨

syntax

DrawIncircle(<triangle>)

example

drawIncircle(ABC)

---

🌸 DrawLine 🌸

this one draws a line joining two or more points 📏 if you want thicker or thinner lines, pair it with the Linethickness command 🎀 under the hood it uses the PiCTeX \putrule command for horizontal and vertical lines, and the \plot command for everything else, so the orientation kinda decides the method 🧚

syntax

DrawLine( <points> [, <points>] )

notes

• <points> is any sequence of two or more point names.
• <expr> is any numerical expression.
• Lines get drawn in the order you specify them 💅
• Lines are separated by a comma.

examples

drawline(AB)
drawline(BCDE)
drawline(FG, HJK, PQRST)

---

🧚 DrawPerpendicular 🧚

this draws the perpendicular from a point over to a line, so simple it's iconic ✨

syntax

DrawPerpendicular(<point>, <line)

example

drawPerpendicular(P,AB)

---

🍓 DrawPoint 🍓

this draws the point-symbol right at the point-location 📍 quick heads up: no commas between point names, bestie 🙅‍♀️ the default point-symbol is a bullet, unless an optional point-symbol (or string of characters) was set in the associated point command 💜

syntax

DrawPoint(<point> [<point> ..])

examples

drawpoint(T4)
drawpoint(ABCDEF)
drawpoint(P1 P2 P3 P4)

---

🦋 DrawRightangle 🦋

this one draws the standard right-angle symbol in the internal angle you pick, sized by <expr> 📐 the <expr> can be any numerical expression, so get creative 🌈

syntax

DrawRightangle(<angle>, <expr>)

notes

• The <expr> can be any numerical expression.

example

drawRightangle(ABC,3)
drawRightangle(ABC,PQ)
var d=5
drawRightangle(ABC,d)

---

🎀 DrawSquare 🎀

this draws a square, defined by its side length and the point-name of its centre 🟪 the <sidelength> can be any numerical expression, periodt 💅

syntax

DrawSquare(<centerpoint>, <sidelength>)

examples

drawSquare(P,5)
var s2=3, j=2
drawSquare(P,s2)
drawSquare(P, s2*4/(3*j))
drawSquare(P,AB)

---

🔥 DrawThickArrow 🔥

this draws thick arrow(s) joining two points 🏹 the arrow points in whatever order you wrote the points, so the direction is literally built in 🫶 the shape of the arrowhead is controlled by the ArrowShape command, so go check that one too 👑

syntax

drawThickArrow(<line> [,<line>,...])

examples

drawThickarrow(BC)
drawThickarrow(PQ, RS)

---

💜 DrawThickLine 💜

this draws thick line(s) joining two points 🩵 same deal as the arrow one: the direction follows the point order you specify 🧭 and if you want to change how thick it is, use the Linethickness command 🌸

syntax

drawThickLine(<line> [,<line>,...])

examples

drawThickline(BC)
drawThickline(PQ, RS)

---

🌈 InputFile 🌈

this one inputs a plain text file full of mathsPIC commands 📂 you can also input the file several times, and when you do, this command acts like a DO--LOOP 🔁 the <loopnumber> can be any numerical expression, and if it isn't a whole number, mathsPIC rounds it down to the nearest integer 🙃 also check out the beginLOOP ... endLOOP commands while you're in here 💖

syntax

inputFile[*](<filename>)[<loopnumber>]

notes

• The inputfile* command inputs a file verbatim, meaning a file with no mathsPIC commands in it, like a file containing only PiCTeX commands or data-points for plotting etc. 📊
• The inputfile* command has no <loopnumber> option, so don't even try 🙅‍♀️
• Note also that PiCTeX requires an ODD number of points 🚨

examples

inputFile(myfile.dat)[4]
inputFile*(mycurvedata.dat)

---

⭐ LineThickness ⭐

this sets a particular line thickness 📏 linethickness(default) puts the working line thickness back to the default value of 0.4pt 🩷 you can grab the current value (in current units) using the var command, which is super handy when you're drawing figures with thick lines 🫶

syntax

LineThickness(<expr><units>)
LineThickness(default)
var t = _linethickness_

notes

• This command also sets the font to cmr and the plotsymbol to \CM . 🔤 and it sets the rule thickness for drawing horizontal and vertical lines too 📐
• It is important to include a leading zero with decimal fractions less than one, so write 0.5, not .5 🙏

examples

linethickness(2pt)
var t=3
linethickness((t)pt)
lineThickness((2*t)pt)
linethickness(default)
var t = _linethickness_

⚠️ caution: there's a similar PiCTeX command with the same name 😳 but it has a different syntax, so don't mix them up, bestie!

---

👑 PAPER 👑

this defines the plotting area using the options units(), xrange(), yrange(), axes(), and ticks() 📄 the units() argument needs a numeric value plus a valid TeX length unit: mm, cm, pt, pc(pica), in(inch), bp(big point), dd(didot), cc(cicero), or sp(scaled point) 📐 the X and Y axes can even have different units (check the second example below, it's giving 🤩) the axes() arguments XYTBLR refer to the X and Y axes, plus the Top, Bottom, Left and Right axes 🧭 putting a * after one of the axes disables ticks on that axis 🙈 and the X and Y axes pass through the zeros, always 💜

examples

paper{units(1cm),xrange(0,10),yrange(0,10)}
paper{units(2cm,1cm),xrange(0,10),yrange(0,10),axes(LB)}
paper{units(1mm),xrange(0,100),yrange(0,100),axes(XY)}
paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRTBXY),ticks(1,1)}
paper{units(1cm),xrange(-5,5),yrange(-5,5),axes(LRT*B*)}

---

🧚 POINT 🧚

this defines a new point by giving a new point name some coordinates 📍 the * option re-allocates coordinates to a point name that already exists, so it's like a glow-up for existing points ✨

syntax

POINT[*](<name>){<point>}[symbol=<chars>, radius=<expr>]
POINT[*](<name>){<location>}[symbol=<chars>, radius=<expr>]

notes

• <name> is one leading letter plus a maximum of three trailing digits 🔠
• <chars> is any TeX string allowed in an \hbox{} 🧁
• <expr> is any numerical expression 🌈
• The polar(r,theta) option defaults to radians for the angle theta 📐 to work in degrees, you must append <deg>, e.g. polar(r,theta deg) 🙃 you can use <direction()> and <directiondeg()> to replace theta too 🦋 and the term vector(AB) means "use the same (r, theta) as AB" 💅

examples

point(A){5,5}
point(B2){22,46}[symbol=$\odot$]
point(B2){22,46}[symbol=circle(2),radius=5]
var r=3
point(B2){22,46}[symbol=square(3),radius=r]
point(B123){22,46}[radius=5]
point(D2){B2, shift(5,5)}
var s = 3
point(D2){B2, shift(2*s,4*s)}
point(D3){D2, polar(6,32 deg)}
point(D4){D2, polar(6,1.2 rad)}
point(D4){D2, polar(6, direction(AB))}      %% radians by default
point(D4){D2, polar(6, directiondeg(AB) deg)}
point(G2){Q, rotate(P, 23 deg)}
point(G2){Q, vector(AB)}
point(D2){intersection(AB,CD)}
point(F){PointOnLine(AB,5.3)}
point(G){perpendicular(P,AB)}
point(H){circumcircleCenter(ABC)}
point(J){incircleCenter(ABC)}
point(K){excircleCenter(ABC,BC)}
point*(A){6,3}
point*(P){Q}
point*(B){B, shift(5,0)}
point*(P){xcoord(J),ycoord(K)}

---

🩷 PointSymbol 🩷

this lets you change the default point-symbol \bullet (which has a zero line-free radius) to something cuter 🫧 it's especially useful when a whole set of points uses the same symbol, like when you're drawing graphs 📈 you can reset the point-symbol back to the default \bullet with PointSymbol(default) 🔄

syntax

PointSymbol(<symbol>, <line-free-radius>)
PointSymbol(default)

notes

• The PointSymbol command only influences subsequent point commands, so order matters 🕰️
• The optional square bracket of the point command overrides the PointSymbol command 💪

examples

PointSymbol($\odot$, 0.7)
PointSymbol(default)

---

💻 SYSTEM 💻

this lets you access the command line and run standard Linux commands from inside mathsPIC 🖥️ a really important use is running a Perl program 🐪

syntax

System("<command>")

notes

• The <command> string must be in inverted commas (aka double quotes) 💬

example

system("dir > mydir-listing.txt")
system("perl myperlprogram.pl")

---

🔮 SHOW.... 🔮

this makes mathsPIC hand back the value of a calculation or a specified parameter, like the size of an angle or the length of a line ✨ the result shows up in the output-file as a commented line 💬 which means you can tweak your mathsPIC commands based on the calculations 🤯 there are currently five such commands as follows 💖

syntax

showLength(AB)
showAngle(ABC)       % returns angle in radians
showAngledeg(ABC)    % returns angle in degrees
showArea(ABC)
showPoints
showVariables

---

🎀 TEXT 🎀

this places a text-string at a specific location 💌 by default the text is centred vertically and horizontally on the specified point 🎯 but you can also place text relative to a point using the PiCTeX position options l t r B b, which line up the (l)eft edge, (r)ight edge, (t)op edge, (B)aseline, or (b)ottom edge of the text box with the point-location 📦

🚨 heads up: the default units for the angle argument of the polar() expression are radians, so you MUST append deg if you want to work in degrees! 🙏

syntax

text(<string>){<location>}[<position options>]
text(<string>){<pointname>, shift(<x>,<y>)}[]
text(<string>){<pointname>, polar(<r>,<angle>[rad])}[]

examples

text(A){5,6}
text($A_1$){A1, shift(2, 2)}
text(Z2){Z2, shift(5, -5)}[tr]
text(Z3){Z2, polar(5, 20 deg)}[Br]
text(Z4){Z2, polar(5, 1.34 rad)}
text(\framebox{Z5}){Z5}

---

🌟 VAR 🌟

the var command defines scalar variables 🔢 it can be any numerical expression 🧮 a variable-name has to begin with a single letter (upper or lower case) and can have up to a maximum of four digits after it 🔠 if you need a fancier variable name, the simple workaround is a mathsPIC macro, since any string can be allocated via macros (see the beginning of this chapter for details on macros) 🫶

Okay so, this is where the var command gets a little tricky, bestie 🫶 Variables, constants, and points all share the same name structure, which means a variable can have the same name as a point 👀 That's why we suggest points get uppercase letters and variables and constants get lowercase letters 🔠✨

Here's the catch: you can reallocate new values to existing variable names, and mathsPIC won't warn you when it happens 😭 No warning, no nothing. So if you'd rather be told when you accidentally overwrite something, use the const command instead, because mathsPIC does throw an error if you try to reallocate a constant 🛡️💅

🎀 syntax

var  <name> = <expr>

💜 notes

Besides the regular mathematical functions, these mathsPIC functions also work with the var command 🧚

angle(<three-points>)          % returns angle in radians
angledeg(<three-points>)       % returns angle in degrees
area(<three-points>)
xcoord(<point>)
ycoord(<point>)
direction(<two-points>)     % returns angular direction in radians
directiondeg(<two-points>)  % returns angular direction in degrees

🌸 examples

var r = 20, r4 = r3*tan(0.3), j = (r*2e3)**2,  r5 = AB
var e = _e_, p1 = _Pi_
var t = _linethickness_  % returns linethickness in current units
var g137 = angle(ABC)    %(default: returns in radians)
var g = angledeg(ABC)    % angle in degrees
var h = area(ABC)
var x2 = xcoord(A), y2 = ycoord(A)
var m5 = 12 rem 3     % remainder after dividing by 3
var r1 = direction(PQ)   % in radians
var d1 = directiondeg(PQ)

---

✨ SEE ALSO ✨

The mathsPIC package manual and examples 📚🦋

✨ BUGS ✨

Bugs go to Dick Nickalls (dick [AT] nickalls [dot] org) or to Apostolos Syropoulos 🐛💖

---

Bye bestie, that's the whole page 🌈 Thanks for sticking with me through all three parts! This one came from the mathsPIC perl version, last updated April 26, 2010 🍓💅