{{indexmenu_n>999}} ====== Add ====== ### //pl2 = Graphics.Add(pl, Element1, Element2, ..., Options)// returns a copy of the [[documentation:language_reference:objects:graphics:start|Graphics object]] //pl// with lines, curves, arcs, texts, bitmaps or other Graphics objects added to it; //pl// itself stays as it is. //pl.Add(Element1, Element2, ..., Options)// adds them to //pl// itself and returns nothing. ### ### A point is given as //{x, y}//, a fraction of the width and of the height of the page: (0,0) is the lower left and (1,1) the upper right corner. Widths of lines, radii and the height of texts are fractions of $\sqrt{\mathrm{width} \cdot \mathrm{height}}$ of the page, so that a circle stays round on a page of any shape. ### ===== Input ===== * //pl// : a Graphics object, for example made by //[[documentation:language_reference:objects:graphics:functions:new|Graphics.New()]]// or //[[documentation:language_reference:objects:graphics:functions:plot|Graphics.Plot()]]//. * //Element1, Element2, ...// : one or more elements, each one of * a line, a list of points //{ {x1, y1}, {x2, y2}, ...}//, joined by straight pieces. * a curve, a list of points //{ {xL1, yL1, x1, y1, xR1, yR1}, {xL2, yL2, x2, y2, xR2, yR2}, ...}//, joined by cubic Bezier pieces. Each point $(x, y)$ comes with two control points: $(x_L, y_L)$ for the piece that ends at the point and $(x_R, y_R)$ for the piece that starts at it. The piece from point $n$ to point $n+1$ starts in the direction of $(x_{R,n}, y_{R,n})$ and arrives from the direction of $(x_{L,n+1}, y_{L,n+1})$; a control point on the point itself gives a sharp corner. * an arc, //{"Arc", {x, y}, R}// for a circle with centre //{x, y}// and radius //R//, or //{"Arc", {x, y}, R, Theta1, Theta2}// for the part from the angle //Theta1// to //Theta2//, counterclockwise. The angles are in radians, measured from the horizontal axis and taken modulo $2\pi$; when //Theta2// is smaller than //Theta1// the arc runs through 0, so //{"Arc", {x, y}, R, 3*Pi/2, Pi/2}// is the right half of a circle. * a text, given as three elements: the string, //x// and //y//, for example //pl.Add("text", 0.5, 0.9)//. The point is the left end (or the middle or the right end, see //"Alignment"//) of the line the letters stand on. * a bitmap, //{"BitMap", {x1, y1}, {x2, y2}, Pixels}//, with //{x1, y1}// the lower left and //{x2, y2}// the upper right corner of the rectangle it fills. //Pixels// is a list of rows, the first row at the top, each a list of pixels. A pixel is a number (grey), //{grey}//, //{r, g, b}// or //{r, g, b, t}//, each from 0 to 255 (values outside are clipped), with //t// the transparency, 0 opaque and 255 fully transparent. * a bitmap with a transparent color, //{"BitMap", {x1, y1}, {x2, y2}, Pixels, TransparentColor}//. The pixels with the red, green and blue of //TransparentColor//, given as a pixel, become fully transparent, or get the transparency //t// of //TransparentColor// when it is given as //{r, g, b, t}//. * a bitmap made by a function, //{"BitMap", {x1, y1}, {x2, y2}, ColorFunction, M1, M2, ...}//, with //M1//, //M2//, ... matrices of the same size (Lua tables or [[documentation:language_reference:objects:matrix:start|Matrix]] objects). The pixel in row $i$ and column $j$, row 1 at the top, gets the color //r, g, b = ColorFunction(Re M1[i][j], Im M1[i][j], Re M2[i][j], Im M2[i][j], ...)//, each from 0 to 1 (values outside are clipped). * a [[documentation:language_reference:objects:bitmap:start|BitMap]] object. * a Graphics object. A copy of it is added as a layer, on top of what is on //pl//; changing it afterwards does not change //pl//. A layer keeps its own size and position on the page, in mm (see [[documentation:language_reference:objects:graphics:start#the_page|the page]]). * Options : (optional) A table of options. They apply to all elements of the call. Possible options are: * //"Color"// : 32 bit integer 0xAARRGGBB, the color of lines, curves, arcs and texts. Default value 0x000000 (opaque black) * //"Transparancy"// : Integer from 0 to 255, a transparency on top of that of //"Color"// (0 is opaque, 255 fully transparent). The two opacities multiply. Default value 0 * //"Line Width"// : Real, the width of lines, curves and arcs. Default value 0.001 * //"Close"// : Boolean, close a line or a curve by joining the last point to the first, or an arc through its centre, and fill it with //"Fill Color"//. Default value false * //"Fill Color"// : 32 bit integer 0xAARRGGBB, the color that fills a closed line, curve or arc. A fully transparent color, for example 0xFF000000, closes it without filling. Default value 0x000000 (opaque black) * //"Fill Transparancy"// : Integer from 0 to 255, a transparency on top of that of //"Fill Color"//. Default value 0 * //"Size"// : Real, the height of a text. Default value 0.05 * //"Alignment"// : String, //"l"//, //"c"// or //"r"//: the point of a text is its left end, its middle or its right end. Default value "l" * //"Angle"// : Real, a text is turned by //"Angle"// (radians, counterclockwise) about its point. Default value 0 * //"Font"// : String, the PostScript name of the font of a text, see [[documentation:language_reference:objects:graphics:start#text|text]]. Default value "TimesNewRomanPSMT" * //"Pixelated"// : Boolean, draw a bitmap with sharp square pixels instead of smoothing between the pixels when it is enlarged. Default value false for a bitmap of pixels, true for a bitmap made by a //ColorFunction// * //"Layer"// : Integer or a list of integers, the layer to add to. 0 is //pl// itself, 1 the first layer added to it, 2 the second, and -1 the last one, -2 the one before. A list //{n1, n2, ...}// adds to layer //n2// of layer //n1//, and so on. The panels of a grid of panels made by //Graphics.Plot// are its layers 1, 2, ... Default value 0 * //"alpha"//, //"Fill alpha"// : Integers from 0 to 255, an opacity (255 opaque, 0 fully transparent), the older form of //"Transparancy"// and //"Fill Transparancy"//. Default value 255 ===== Output ===== * //pl2// : a new Graphics object, //pl// with the elements added. //pl.Add// returns nothing. ### Within one Graphics object the bitmaps are drawn first, then the lines, the curves, the arcs and the texts, each in the order in which they were added. The layers are drawn after that, so a bitmap that should lie on top of a line is put in a layer. A grey background below other bitmaps is a bitmap of one pixel, //{"BitMap", {0,0}, {1,1}, { {224} }}//, added first. ### ===== Example ===== ### A line, a filled triangle, a curve, a circle, a quarter of a disc, a bitmap, two texts and a layer on an A4 page. ### ==== Input ==== -- an empty page, A4 in landscape; a point {x, y} is a fraction of the width and the height of the page pl = Graphics.New() -- a line through three points, 0.004 wide, blue pl.Add({ {0.05,0.55}, {0.15,0.9}, {0.25,0.55} }, {{"Line Width",0.004}, {"Color",0x0000C0}}) -- a closed triangle, filled with a half transparent red pl.Add({ {0.3,0.55}, {0.4,0.9}, {0.5,0.55} }, {{"Close",true}, {"Fill Color",0x80FF0000}}) -- a curve of two pieces; each point is {xL,yL, x,y, xR,yR}, with the control points before and after it pl.Add({ {0.55,0.55, 0.55,0.55, 0.55,0.9}, {0.65,0.9, 0.75,0.9, 0.85,0.9}, {0.95,0.55, 0.95,0.55, 0.95,0.55} }, {{"Line Width",0.004}, {"Color",0x00A000}}) -- a circle, and a quarter of a disc from 0 to 90 degrees, closed through its centre and filled pl.Add({"Arc", {0.15,0.25}, 0.1}) pl.Add({"Arc", {0.3,0.2}, 0.1, 0, Pi/2}, {{"Close",true}, {"Fill Color",0xFF8000}}) -- a bitmap of 3 by 2 pixels, the first row at the top, drawn with sharp pixels pl.Add({"BitMap", {0.45,0.1}, {0.6,0.35}, { {{255,0,0}, {0,160,0}, {0,0,255}}, {0, 128, 255} }}, {{"Pixelated",true}}) -- texts: centred, and turned by 90 degrees pl.Add("Graphics.Add", 0.5, 0.45, {{"Size",0.06}, {"Alignment","c"}}) pl.Add("turned", 0.68, 0.1, {{"Angle",Pi/2}, {"Color",0x0000C0}}) -- a layer: a small page of its own, 60 mm by 50 mm with its lower left corner at (220 mm, 15 mm) Inset = Graphics.New({{"Canvas.Size.X",60}, {"Canvas.Size.Y",50}, {"Canvas.Origin.X",220}, {"Canvas.Origin.Y",15}}) Inset.Add({ {0,0}, {1,0}, {1,1}, {0,1} }, {{"Close",true}, {"Fill Color",0xE0E0E0}}) pl.Add(Inset) -- the option Layer adds to layer 1, so (0.5, 0.5) is the middle of the inset pl.Add("inset", 0.5, 0.5, {{"Layer",1}, {"Alignment","c"}, {"Size",0.15}}) print("lines", pl.NLine, "curves", pl.NCurve, "arcs", pl.NArc, "texts", pl.NText, "bitmaps", pl.NBitMap, "layers", pl.NLayer) -- the function form returns a new Graphics object and leaves pl as it is pl2 = Graphics.Add(pl, "a third text", 0.05, 0.02) print("texts", pl.NText, pl2.NText) file = io.open("Add.svg", "w") file:write(Graphics.ToSVG(pl, {{"RelativeSize",true}})) file:close() ==== Result ==== lines 2 curves 1 arcs 2 texts 2 bitmaps 1 layers 2 texts 2 3 ### The script writes //Add.svg//. The text "inset" is in the layer, so it is not counted among the texts of //pl//; //pl.NLayer// counts //pl// itself and its one layer. The circle is round although the page is not square, because its radius is a fraction of $\sqrt{\mathrm{width} \cdot \mathrm{height}}$. ### {{:documentation:language_reference:objects:graphics:functions:add_elements.png?nolink&600 |}} ===== Table of contents ===== {{indexmenu>../#2|tsort}}