The ‘pst-lens’ package A PSTricks package for lens

Denis Girou^{∗} and Manuel Luque^{†}

Version 1.0 February 19, 2001

Documentation revised February 19, 2001

Abstract

This package define a lens which can be used in various contexts to simulate the effect of a lens, using the unique macro \PstLens, with some customization parameters.

It is also a good example of the great power and flexibility of PSTricks, as in fact it is a very short program (it body, without considering the various customizations, is only 7 lines long!) but nevertheless powerful.

And last, it is also a good pedagogical example of how to design and program high level graphic objects above PSTricks own ones.

Contents

1 Introduction

‘pst-lens’ offer a unique macro with some parameters to interact on it.

The syntax is simply: \PstLens[optional parameters](x,y) {Object}

(x,y) is a PSTricks coordinate, which as usual is taken as (0,0) if it is not defined.

To use the lens, we must define a pspicture environment, optionally draw the object and then call the \PstLens macro on it.

2 Usage

We will use the following textual object to illustrate our examples (note that we must define the reference point at the left bottom corner, as it is the normal behavior of PSTricks):

∗CNRS/IDRIS — Centre National de la Recherche Scientifique / Institut du Développement et des Ressources en Informatique Scientifique — Orsay — France — <Denis.Girou@idris.fr>.

†<Mluque5130@aol.com>. The original idea and the first version of the lens were from Manuel Luque.

Best wishes Caroline, for this new year 2001 !

1 \def\Wishes{{%
2 \rput[lb](0,0){%
3 \Large
4 \begin{minipage}{3cm}
5  \centering
6  \textbf{Best wishes}\\
7  Caroline,\\
8  for this new year\\
9  \Huge 2001 !
10 \end{minipage}}}}

11

12 \Wishes

2.1 Parameters

There are 9 specific parameters defined to change the way the lens works:

LensMagnification (real) : magnification to apply for the lens (Default: 1 — no magnification).

1 \begin{pspicture}(0,-1.5)(3,4)
2 \Wishes
3 \PstLens[LensMagnification=2](2,2){\Wishes}
4 \end{pspicture}
5 \hfill
6 \begin{pspicture}(0,-1.5)(3,4)
7 \Wishes
8 \PstLens[LensMagnification=4](1,2.4){\Wishes}
9 \end{pspicture}
10 \hfill
11 \begin{pspicture}(0,-1.5)(3.5,4)
12 \Wishes
13 \PstLens[LensMagnification=0.5](1,1){\Wishes}
14 \PstLens[LensMagnification=-0.5](2.5,3){\Wishes}
15 \end{pspicture}

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

LensSize (real or length) : value of the radius of the glass of the lens (Default: 1 ).

Note that the size of the handle will change accordingly.

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(0,-4)(3,3.5)
2 \Wishes
3 \PstLens[LensSize=2](1,1){\Wishes}
4 \PstLens[LensSize=0.5](3,3){\Wishes}
5 \end{pspicture}

LensRotation (real) : rotation angle applied to the lens (Default: 0 — no rotation).

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(0,-1)(3,3.8)
2 \Wishes
3 \PstLens[LensRotation=80]{\Wishes}
4 \PstLens[LensRotation=-108.5](2,2){\Wishes}
5 \end{pspicture}

LensHandle (boolean) : boolean value to choose between to draw a handle for the lens or not. (Default: true — handle).

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(3,3.5)
2 \Wishes
3 \PstLens[LensHandle=false](2,2){\Wishes}
4 \end{pspicture}

LensHandleWidth (real or length) : width of the handle (Default: 0.2 for LensSize=1 ).

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(0,-2.5)(3,3.5)
2 \Wishes
3 \PstLens[LensHandleWidth=0.1]{\Wishes}
4 \PstLens[LensHandleWidth=4mm](2,2){\Wishes}
5 \end{pspicture}

LensHandleHeight (real or length) : height of the handle (Default: 2.5 for LensSize=1 ).

Take care that this length is between the center of the glass and the bottom of the handle.

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(0,-2)(3,3.5)
2 \Wishes
3 \PstLens[LensHandleHeight=15mm]{\Wishes}
4 \PstLens[LensHandleHeight=4](2,2){\Wishes}
5 \end{pspicture}

LensStyleHandle (style) : name of the PSTricks style for the handle. (Default: LensStyleHandle).

Its default value is:

1 \newpsstyle{LensStyleHandle}{%
2 fillstyle=gradient,framearc=0.6,linewidth=0.5\pslinewidth,
3 gradmidpoint=0.5,gradangle=\PstLens@Rotation,
4 gradbegin=Brown,gradend=Salmon}

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(0,-2.5)(3,3.5)
2 \Wishes
3 \newpsstyle{HandleYellow}{%
4  linecolor=red,framearc=1,
5  fillstyle=solid,fillcolor=yellow}
6 \PstLens[LensHandleWidth=0.5,
7  LensStyleHandle=HandleYellow]
8  {\Wishes}
9 \newpsstyle{HandleCrosshatch}{%
10  fillstyle=crosshatch*,fillcolor=white}
11 \PstLens[LensStyleHandle=HandleCrosshatch]
12  (2,2){\Wishes}
13 \end{pspicture}

LensShadow (boolean) : boolean value to choose between to draw a shadow for the glass of the lens or not. (Default: true — shadow).

Note that if we redefine the LensStyleGlass parameter without explicitely require a shadow, there will be none even if LensShadow will have the true value.

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(0,-0.5)(3,3.5)
2 \Wishes
3 \PstLens[LensShadow=false](2,2){\Wishes}
4 \end{pspicture}

LensStyleGlass (style) : name of the PSTricks style for the glass. (Default: LensStyleGlass).

It allow to change the appearance of the glass, but its main utility is probably to be able to define the style of the shadow of the glass. Default definition is:

1 \newpsstyle{LensStyleGlass}{%
2 fillstyle=solid,fillcolor=white,
3 shadow=true,shadowcolor=lightgray,shadowsize=0.15,
4 shadowangle=\PstLens@Rotation}

Take care that if we will use later the LensRotation parameter with LensShadow positioned, we must set the value of the shadowangle parameter to \PstLens@Rotation to have the shadow rotate accordingly.

And for better shadow effects, you must look at the ‘pst-blur’ package from Martin Giese.

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(3,4)
2 \Wishes
3 \makeatletter
4 \newpsstyle{DarkShadow}{%
5  fillstyle=solid,fillcolor=white,
6  shadow=true,shadowcolor=darkgray,
7  shadowsize=0.2,
8  shadowangle=\PstLens@Rotation}
9 \makeatother
10 \PstLens[LensRotation=230,
11  LensStyleGlass=DarkShadow](2,2)
12  {\Wishes}
13 \end{pspicture}

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

1 \begin{pspicture}(0,-0.5)(3,3.5)
2 \Wishes
3 \newpsstyle{YellowGlass}{%
4  linecolor=red,linewidth=0.1,
5  fillstyle=solid,fillcolor=yellow}
6 \PstLens[LensStyleGlass=YellowGlass](2,2)
7  {\Wishes}
8 \end{pspicture}

2.2 Shape of the glass

The \PstLensShape macro define the shape of the glass. It default value is a circle, as in real life, but we can redefine it for various effects...

1 \psset{LensMagnification=1.5}
2 \begin{pspicture}(0,-1.8)(4,3.8)
3 \Wishes
4 \renewcommand{\PstLensShape}{\psellipse(2,1)}
5 \PstLens(2,2){\Wishes}
6 \end{pspicture}
7 \hfill
8 \begin{pspicture}(-0.5,-1.8)(4,3.8)
9 \Wishes
10 \renewcommand{\PstLensShape}{\pstriangle(3,1)}
11 \PstLens[LensSize=1.5](2,2){\Wishes}
12 \end{pspicture}
13 \hfill
14 \begin{pspicture}(0,-1.8)(3.5,3.8)
15 \Wishes
16 \renewcommand{\PstLensShape}{%
17  \rput{18}{\pspolygon(1;0)(1;144)(1;288)(1;72)(1;216)}}
18 \PstLens[LensSize=1.5](2,2){\Wishes}
19 \end{pspicture}

20

21 \begin{pspicture}(0,-0.5)(4,3.5)
22 \renewcommand{\PstLensShape}{%
23  \parabola[fillstyle=solid,fillcolor=white](-1,-1.5)(1,2)}
24 \Wishes
25 \PstLens[LensShadow=false,LensHandle=false](1,1){\Wishes}
26 \end{pspicture}
27 \hfill
28 \begin{pspicture}(-1.5,-1)(3.5,3.5)
29 \renewcommand{\PstLensShape}{%
30  \psccurve(-1,-1)(0,1.2)(0.5,-1)(1,0.8)}
31 \Wishes
32 \PstLens[LensSize=2,LensHandle=false](1,1){\Wishes}
33 \end{pspicture}

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

2.3 Examples

We can use the lens for all textual objects and for all PSTricks graphic objects (we use here some versions of tilings and fractals, but only basic ones to avoid requiring too much memory from old TEX systems, to compile the file).

And specially take care to explicitely position the reference point at the left bottom corner and to compute the correct dimensions for the pspicture environment (in our examples, we choose most of the time to include the lens inside the bounding boxes, but we can choose to define them just for the objects).

1 \def\TheEternity{{%
2 \rput[lb](0,0){%
3 \scriptsize
4 \begin{minipage}{3.5cm}
5  \centerline{\normalsize\textbf{L'\'Eternit\'e}}
6 ...
7 \def\TruchetTiling#1#2{{%
8 \rput[lb](0,0){%
9 ...
10 \def\PstSierpinskiTriangle#1{{%
11 \rput[lb](0,0){%
12 ...
13 \def\PstVonKochCurve#1{{%
14 \rput[lb](0,0){%
15 ...

1 \newpsstyle{SimpleGlass}{fillstyle=solid,fillcolor=white}
2 \newpsstyle{SimpleHandle}{fillstyle=solid,fillcolor=white,
3  framearc=0.5}
4 \psset{LensStyleGlass=SimpleGlass,LensStyleHandle=SimpleHandle}

5

6 \begin{pspicture}(-1,-2.5)(5,10.5)
7 \TheEternity
8 \PstLens[LensSize=2,LensMagnification=4,LensRotation=40]
9  (1.5,6){\TheEternity}
10 \PstLens[LensSize=1.5,LensMagnification=2,LensRotation=-20]
11  (0.5,2){\TheEternity}
12 \end{pspicture}
13 \hfill
14 \begin{pspicture}(-2,-2.5)(4,10.5)
15 \TheEternity
16 \PstLens[LensMagnification=0.5,LensRotation=140]
17  (1,8.5){\TheEternity}
18 \PstLens[LensSize=2.5,LensMagnification=3,LensRotation=-100]
19  (2.4,0){\TheEternity}
20 \end{pspicture}

L’Éternité

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Âme sentinelle Murmurons l’aveu De la nuit si nulle Et du jour en feu.

Des humains suffrages Des communs élans Là tu te dégages Et voles selon.

Puisque de vous seules, Braises de satin, Le devoir s’exhale Sans qu’on dise : enfin.

Là pas d’espérance, Nul orietur. Science avec patience, Le supplice est sûr.

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Arthur Rimbaud

L’Éternité

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Âme sentinelle Murmurons l’aveu De la nuit si nulle Et du jour en feu.

Des humains suffrages Des communs élans Là tu te dégages Et voles selon.

Puisque de vous seules, Braises de satin, Le devoir s’exhale Sans qu’on dise : enfin.

Là pas d’espérance, Nul orietur. Science avec patience, Le supplice est sûr.

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Arthur Rimbaud

L’Éternité

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Âme sentinelle Murmurons l’aveu De la nuit si nulle Et du jour en feu.

Des humains suffrages Des communs élans Là tu te dégages Et voles selon.

Puisque de vous seules, Braises de satin, Le devoir s’exhale Sans qu’on dise : enfin.

Là pas d’espérance, Nul orietur. Science avec patience, Le supplice est sûr.

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Arthur Rimbaud

L’Éternité

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Âme sentinelle Murmurons l’aveu De la nuit si nulle Et du jour en feu.

Des humains suffrages Des communs élans Là tu te dégages Et voles selon.

Puisque de vous seules, Braises de satin, Le devoir s’exhale Sans qu’on dise : enfin.

Là pas d’espérance,

Nul orietur.

Science avec patience, Le supplice est sûr.

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Arthur Rimbaud

L’Éternité

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Âme sentinelle Murmurons l’aveu De la nuit si nulle Et du jour en feu.

Des humains suffrages Des communs élans Là tu te dégages Et voles selon.

Puisque de vous seules, Braises de satin, Le devoir s’exhale Sans qu’on dise : enfin.

Là pas d’espérance,

Nul orietur.

Science avec patience, Le supplice est sûr.

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Arthur Rimbaud

L’Éternité

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Âme sentinelle Murmurons l’aveu De la nuit si nulle Et du jour en feu.

Des humains suffrages Des communs élans Là tu te dégages Et voles selon.

Puisque de vous seules, Braises de satin, Le devoir s’exhale Sans qu’on dise : enfin.

Là pas d’espérance,

Nul orietur.

Science avec patience, Le supplice est sûr.

Elle est retrouvée. Quoi ? — L’Éternité. C’est la mer allée Avec le soleil.

Arthur Rimbaud

1 \begin{pspicture}(0,-6)(6,6)
2 \TruchetTiling
3 \PstLens[LensSize=2.5,LensMagnification=2.5](3.5,1)
4  {\TruchetTiling}
5 \end{pspicture}

 1 \newcommand{\PstSierpinskiInternalColor}{red}
 2 \newcommand{\PstSierpinskiExternalColor}{yellow}

3

 4 % The Sierpinski triangle is in a unit circle of radius 1,
 5 % so we must define the "pspicture" accordingly: (-3,-2)(3,3)
 6 \begin{pspicture}(-3,-2)(3,3)
 7 \PstSierpinskiTriangle{3}
 8 \end{pspicture}
 9 \hfill
10 \begin{pspicture}(-3,-2)(3,3)
11 \PstSierpinskiTriangle{3}
12 \psset{LensShadow=false}
13 \PstLens[LensMagnification=2,LensRotation=-80](-1,0)
14  {\PstSierpinskiTriangle{3}}
15 \PstLens[LensSize=2,LensMagnification=5,LensRotation=100,
16  LensHandle=false](1,1){\PstSierpinskiTriangle{3}}
17 \end{pspicture}

18

19 \begin{pspicture}(-1,-2)(11,5)
20 \PstVonKochCurve{3}

21 \PstLens[LensSize=1.2,LensMagnification=2,LensRotation=-50]
22  (1.5,0.6){\PstVonKochCurve{3}}
23 \PstLens[LensSize=2.5,LensMagnification=5,LensRotation=160,
24  LensHandleHeight=2](6.2,0.2){\PstVonKochCurve{3}}
25 \end{pspicture}

Of course, as for all PSTricks objects, we can apply to them some transformations. For instance, we can project them in the 3 dimensional space, with the general \ThreeDput macro or the simple \pstilt one.

1 \psset{LensMagnification=1.5}
2 \begin{pspicture}(0.8,-1.5)(5.3,3)
3 \renewcommand{\PstLensShape}{\psdiamond(1.5,1)}
4 \pstilt{60}{%
5  \Wishes
6  \PstLens[LensSize=1.5](2,2){\Wishes}}
7 \end{pspicture}
8 \hfill
9 \begin{pspicture}(-3,-0.5)(3.5,8)

10 \psset{viewpoint=0.5 -2 5,LensHandleHeight=3.5}
11 \multido{\nPosX=0+-0.8,\nPosY=8+-1.5,\nMag=3+-0.5}{5}{%
12  \ThreeDput(\nPosX,\nPosY,0){%
13  \PstLens[LensMagnification=\nMag](0.6,0.2)
14  {\rput[lb](0,0){Danger!}}}}
15 \end{pspicture}

Best wishes Caroline, for this new year 2001 !

Best wishes Caroline, for this new year 2001 !

Danger! Danger! Danger! Danger! Danger!

And we can also use the lens on non PSTricks graphics, as external images.

 1 \newcommand{\LouiseBrooks}{%
 2 \rput[lb](0,0){%
 3  \includegraphics[width=4cm,height=5cm]{LouiseBrooks}}}
 4 \newpsstyle{SimpleGlass}{linestyle=none}
 5 \psset{LensStyleGlass=SimpleGlass}

6

 7 \begin{pspicture}(0,-1)(4,5)
 8 \LouiseBrooks
 9 \end{pspicture}
10 \hfill
11 \begin{pspicture}(-0.5,-1)(3,5)
12 \PstLens[LensHandle=false,LensSize=1.8,LensMagnification=2]
13  (1.2,2.3){\LouiseBrooks}
14 \end{pspicture}
15 \hfill
16 \newpsstyle{SimpleHandle}{fillstyle=solid,fillcolor=white,
17  framearc=0.5}
18 \psset{LensStyleHandle=SimpleHandle}

19 \begin{pspicture}(0,-1)(4,5)
20 \LouiseBrooks
21 \PstLens[LensSize=1.5,LensMagnification=4]
22  (1.5,2.5){\LouiseBrooks}
23 \end{pspicture}