fpvectorial: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Introduction
2	2
3	3		FPVectorial offers support to read, modify and write vectorial images.
4	4
5	5		Its counterpart library is [[fcl-image]], which works with raster images. FPVectorial comes with a unit which allows to draw a vectorial image to a TFPCustomCanvas, but no routines are provided to convert raster images to vectorial images.
6	6
7	7		## Download
8	8
9	9		fpvectorial is distributed along with Lazarus. You can find it in folder components/fpvectorial of your Lazarus installation.
10	10
11	11		If you have a release version of Lazarus and want the latest version of fpvectorial you can download it by svn from
12	12
13		-	~~`svn co `[`http://svn.freepascal.org/svn/lazarus/trunk/components/fpvectorial`](http://svn.freepascal.org/svn/lazarus/trunk/components/fpvectorial)` fpvectorial`~~
	13	+	```text
	14	+	svn co http://svn.freepascal.org/svn/lazarus/trunk/components/fpvectorial fpvectorial
	15	+	```
14	16
15	17		Downloading the fpvviewer project:
16	18
17		-	~~`svn co `[`https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/applications/fpvviewer`](https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/applications/fpvviewer)` fpvviewer`~~
	19	+	```text
	20	+	svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/applications/fpvviewer fpvviewer
	21	+	```
18	22
19	23		## Current file list
20	24
21	25		FPVectorial is located in the Lazarus directory components/fpvectorial.
22	26
23	27		The central unit is [[doc:fcl/fpvectorial\|fpvectorial]].
24	28
25	29		Readers for various image formats
26	30
27	31		- pdfvectorialreader - Read support for PDF files, supports compression, only reads the first page
28	32		- avisocncgcodereader - Read support for the G-Code from the Aviso CNC machine
29	33		- cdrvectorialreader - Initial work of a reader support for Corel Draw CDR files
30	34		- dxfvectorialreader - Read support for DXF, the Drawing eXchange Format utilized by the AutoCAD
31	35		- svgvectorialreader - Read support for SVG
32	36		- epsvectorialreader - Read support for Encapsulated PostScript
33	37		- wmfvectorialreader - Read support for WMF (Windows metafile, cross-platform!)
34	38
35	39		Writers for various image formats
36	40
37	41		- avisocncgcodewriter - Write support for the G-Code from the Aviso CNC machine
38	42		- svgvectorialwriter - Write support for SVG. The most advanced writer at the moment. Supports lines, curves and text. Supports pen color and width.
39	43
40	44		Other units
41	45
42	46		- fpvtocanvas - Converts a vectorial document to a TFPCustomCanvas descendent (like TCanvas). Essentially converts the vectorial image to a raster image
43	47		- fpvutils - Utility functions which don't belong to fpvectorial.pas or that would bring unwanted dependencies to it. Color conversion functions.
44	48		- pdfvrlexico, pdfvrsemantico, pdfvrsintatico, avisozlib - Other units from the PDF reader, don't use directly
45	49
46	50		## Formats
47	51
48	52		### PDF
49	53
50	54		The PDF format is developed by Adobe (tm) and it is fully documented. Inside, PDF is simply text, so it is rather easy to parse, but parts of this text are usually can be compressed.
51	55
52	56		Link to the PDF Reference: <http://www.adobe.com/devnet/pdf/pdf_reference.html>
53	57
54	58		### CorelDraw
55	59
56	60		Corel does not release public documentation for its CorelDraw file format. Any information about this format depends on reverse engineering and guessing. The format is binary and consists of a tree of chunks.
57	61
58	62		See also [[fpvectorial\|fpvectorial#fpcorelexplorer]]
59	63
60	64		### SVG
61	65
62	66		Scalable Vectorial Graphics (SVG) is a standard from W3C for vectorial graphics. It is the native format of Inkscape and stores its data as a single, uncompressed XML file with the extension ".svg".
63	67
64	68		Link to the specification: <http://www.w3.org/TR/SVG/>
65	69
66	70		A very serious shortcoming in SVG is that it does not allow real world units to be specified in the drawing routines, only pixel values accepted, which makes it impossible to have a document with real world units. This can be worked around by simply hardcoding to a fixed DPI resolution, which is 90 DPI for Inkscape. Read more here:
67	71
68	72		- <http://stackoverflow.com/questions/1346922/svg-and-dpi-absolute-units-and-user-units-inkscape-vs-firefox-vs-imagemagick>
69	73		- <http://www.inkscapeforum.com/viewtopic.php?f=16&t=5904>
70	74		- <http://www.inkscapeforum.com/viewtopic.php?f=16&t=3700&p=17179&hilit=units+path#p17179>
71	75
72	76		Following Inkscape and the Opera Browser, FPVectorial also hardcodes to 90 DPI.
73	77
74	78		As of February 2014 support for SVG is partial.
75	79
76	80		### DXF
77	81
78	82		The Drawing eXchange Format from Autodesk AutoCAD. This format is documented, but the quality of the documentation is rather low, lacking adequate explanations.
79	83
80	84		The format itself is rather simple, composed by text. Each unit is composed of two lines, the first one being a number describing the type of data and then another line with the value itself, which might be text or a number.
81	85
82	86		The most common problem in other DXF reading libraries is that they don't support the actual DXF writen by newer versions of AutoCAD. This is not the case with fpvectorial, which was tested with AutoCAD 2000 and also the previous simpler formats.
83	87
84	88		Link to the documentation:
85	89
86	90		- <http://www.autodesk.com/techpubs/autocad/acad2000/dxf/>
87	91
88	92		The software fpvviewer can be utilized to show the internal structure of a DXF file. This software can be found in the lazarus-ccr svn in applications/fpvviewer. More info here: [[fpvectorial\|fpvectorial#fpvviewer]]
89	93
90	94		### WMF
91	95
92	96		The Windows Metafile (WMF) format was originally designed for Microsoft Windows in the 1990s. The files can contain both vector graphics and bitmap components and consist of a list of drawing commands with parameters which are originally passed directly to the Windows Graphics Device Interface (GDI); in fpvectorial, however, they are converted to graphics objects which makes the format platform-independent.
93	97
94	98		The file structure is documented at <http://msdn.microsoft.com/en-us/library/cc250370.aspx>
95	99
96	100		### PostScript
97	101
98	102		PostScript is a graphics drawing programming language and fpvectorial has an interpreter which can execute PostScript and convert its commands into its internal format. This is done by reader modules, for example epsvectorialreader. The interpreter is separated into a Tokenizer and an Executer. The tokens are classified into 3 types: Procedures, ExpressionTokens and Comments. Procedures are inside a {..} block in PostScript and in FPVectorial they are not tokenezed in the first pass, but instead on the first usage. The entire document is tokenized in one run, before executing the tokens, except for the procedures. The PostScript interpreter contains a Stack and a lookup Dictionary, as specified in PostScript.
99	103
100	104		PostScript can be embedded into various formats, and the interpreter currently supports the EPS format.
101	105
102	106		References:
103	107
104	108		- <http://en.wikipedia.org/wiki/Encapsulated_PostScript>
105	109		- <http://partners.adobe.com/public/developer/en/ps/PLRM.pdf>
106	110
107	111		### LAS
108	112
109	113		LAS is geospatial data encoded in the ASPRS LASer (LAS) file format, which exists in versions 1.0, 1.1, 1.2, 1.3 and 1.4. Version 2.0 does not yet exist as of December 2011.
110	114
111	115		References:
112	116
113	117		- <http://en.wikipedia.org/wiki/LibLAS>
114	118		- <http://www.asprs.org/a/society/committees/lidar/lidar_format.html>
115	119		- <http://trac.liblas.org/wiki/Software>
116	120		- <http://www.cs.unc.edu/~isenburg/lastools/>
117	121		- <http://www.fugroviewer.com/>
118	122		- Example las file: www.appliedimagery.com/downloads/sampledata/Serpent%20Mound%20Model%20LAS%20Data.las
119	123		- Specification docs up to 1.3: <http://www.asprs.org/a/society/committees/standards/lidar_exchange_format.html>
120	124		- Specification for 1.4: <http://www.asprs.org/Press-Releases/LAS-1-4-Draft-Specification-Released-by-ASPRS.html>
121	125
122	126		## Types of data in FPVectorial
123	127
124	128		FPVectorial holds lists of three types of objects: paths, text and entities.
125	129
126	130		Essentially paths are sequences of points, through which run lines and bezier curves. A path can be a line, a bezier, a polyline, a polybezier or any combination of these elements. The main characteristic of paths is that they can be utilized to guide a milling machine, also known as CNC machine, into physically executing the drawing. Before being able to execute a drawing which contains either text or entities in a CNC machine, these items need to be converted to paths.
127	131
128	132		Text, just like the name says are strings drawn with fonts.
129	133
130	134		Entities are things like circles, arcs, ellipses, rotated ellipses, etc.
131	135
132	136		## Usage examples
133	137
134	138		### Format conversion
135	139
136	140		This example loads a PDF, converts it to G-Code and writes the G-Code to a TStrings descendent
137	141
138	142		``` pascal
139	143		uses
140	144		fpvectorial, pdfvectorialreader, avisocncgcodewriter;
141	145
142	146		var
143	147		Vec: TvVectorialDocument;
144	148		begin
145	149		if dialogoAbrir.Execute() then
146	150		begin
147	151		Vec := TvVectorialDocument.Create;
148	152		try
149	153		Vec.ReadFromFile(dialogoAbrir.FileName, vfPDF);
150	154		Vec.WriteToStrings(synCodigo.Lines, vfGCodeAvisoCNCPrototipoV5);
151	155		finally
152	156		Vec.Free;
153	157		end;
154	158		end;
155	159		end;
156	160		```
157	161
158	162		### Adding paths, bezier lines and text
159	163
160	164		This example shows how to add various elements.
161	165
162	166		``` pascal
163	167		{
164	168		Author: Felipe Monteiro de Carvalho
165	169
166	170		License: Public Domain
167	171		}
168	172		program fpvwritetest;
169	173
170	174		{$mode objfpc}{$H+}
171	175
172	176		uses
173	177		fpvectorial, svgvectorialwriter;
174	178
175	179		const
176	180		cFormat = vfSVG;
177	181		cExtension = '.svg';
178	182		var
179	183		VecDoc: TvVectorialDocument;
180	184		Vec: TvVectorialPage;
181	185		s : String;
182	186		begin
183	187		VecDoc := TvVectorialDocument.Create;
184	188		try
185	189		// All documents are 10cm x 10cm
186	190		VecDoc.Width := 100;
187	191		VecDoc.Height := 100;
188	192
189	193		Vec := VecDoc.AddPage();
190	194		Vec.Width := VecDoc.Width;
191	195		Vec.Height := VecDoc.Height;
192	196
193	197		// ...
194	198
195	199		// multi_test_1 Combines various elements
196	200		Vec.Clear;
197	201		Vec.StartPath(0, 20);
198	202		Vec.AddLineToPath(30, 30);
199	203		Vec.EndPath();
200	204		Vec.StartPath(0, 0);
201	205		Vec.AddLineToPath(100, 0);
202	206		Vec.AddLineToPath(100, 100);
203	207		Vec.AddLineToPath(0, 100);
204	208		Vec.AddLineToPath(0, 0);
205	209		Vec.EndPath();
206	210		Vec.StartPath(0, 0);
207	211		Vec.AddLineToPath(10, 10);
208	212		Vec.AddBezierToPath(10, 20, 20, 20, 20, 10);
209	213		Vec.AddLineToPath(30, 0);
210	214		Vec.EndPath();
211	215		Vec.AddText(10, 10, 0, '10,10 Some text in english.');
212	216		s := '20, 20 Mówić, cześć, Włosku, Parabéns.';
213	217		Vec.AddText(20, 20, 0, s);
214	218		s := '30, 30 森林，是一个高密';
215	219		Vec.AddText(30, 30, 0, s);
216	220		VecDoc.WriteToFile('multi_test_1' + cExtension, cFormat);
217	221		finally
218	222		VecDoc.Free;
219	223		end;
220	224		end.
221	225		```
222	226
223	227		And here is the output of this example when rendered by the Opera Browser:
224	228
225	229		![](/wiki-images/9/92/Fpvectorial_svg_output.PNG)
226	230
227	231		### Adding Aligned Coordinates
228	232
229	233		One can either add horizontal coordinates:
230	234
231	235		``` pascal
232	236		Vec.AddAlignedDimension(Make2DPoint(100, 50), Make2DPoint(200, 100), Make2DPoint(100, 150), Make2DPoint(200, 150));
233	237		```
234	238
235	239		![](/wiki-images/0/05/Aligned_dimension_horizontal.png)
236	240
237	241		Or add vertical coordinates:
238	242
239	243		``` pascal
240	244		Vec.AddAlignedDimension(Make2DPoint(50, 250), Make2DPoint(100, 200), Make2DPoint(150, 250), Make2DPoint(150, 200));
241	245		```
242	246
243	247		![](/wiki-images/6/68/Aligned_dimension_vertical.png)
244	248
245	249		### Rendering the image into a TCanvas
246	250
247	251		To render a vectorial image into a TCanvas or TFPCustomCanvas use the unit fpvtocanvas and its routines:
248	252
249	253		``` pascal
250	254		unit fpvtocanvas;
251	255		//..
252	256		{@@
253	257		This function draws a FPVectorial vectorial image to a TFPCustomCanvas
254	258		descendent, such as TCanvas from the LCL.
255	259
256	260		Be careful that by default this routine does not execute coordinate transformations,
257	261		and that FPVectorial works with a start point in the bottom-left corner, with
258	262		the X growing to the right and the Y growing to the top. This will result in
259	263		an image in TFPCustomCanvas mirrored in the Y axis in relation with the document
260	264		as seen in a PDF viewer, for example. This can be easily changed with the
261	265		provided parameters. To have the standard view of an image viewer one could
262	266		use this function like this:
263	267
264	268		DrawFPVectorialToCanvas(ASource, ADest, 0, ASource.Height, 1.0, -1.0);
265	269		}
266	270		procedure DrawFPVectorialToCanvas(ASource: TvVectorialPage;
267	271		ADest: TFPCustomCanvas;
268	272		ADestX: Integer = 0; ADestY: Integer = 0; AMulX: Double = 1.0; AMulY: Double = 1.0);
269	273		```
270	274
271	275		And below an example taken from lazarus-ccr/application/fpvviewer
272	276
273	277		``` pascal
274	278		uses fpvtocanvas;
275	279
276	280		procedure TfrmFPVViewer.btnVisualizeClick(Sender: TObject);
277	281		const
278	282		FPVVIEWER_MAX_IMAGE_SIZE = 1000;
279	283		FPVVIEWER_MIN_IMAGE_SIZE = 100;
280	284		FPVVIEWER_SPACE_FOR_NEGATIVE_COORDS = 100;
281	285		var
282	286		Vec: TvVectorialDocument;
283	287		CanvasSize: TPoint;
284	288		begin
285	289		// First check the in input
286	290		//if not CheckInput() then Exit;
287	291
288	292		notebook.PageIndex := 0;
289	293
290	294		Drawer.Clear;
291	295
292	296		Vec := TvVectorialDocument.Create;
293	297		try
294	298		Vec.ReadFromFile(editFileName.FileName);
295	299
296	300		// We need to be robust, because sometimes the document size won't be given
297	301		// also give up drawing everything if we need more then 4MB of RAM for the image
298	302		// and also give some space in the image to allow for negative coordinates
299	303		if Vec.Width * spinScale.Value > FPVVIEWER_MAX_IMAGE_SIZE then CanvasSize.X := FPVVIEWER_MAX_IMAGE_SIZE
300	304		else if Vec.Width < FPVVIEWER_MIN_IMAGE_SIZE then CanvasSize.X := Drawer.Width
301	305		else CanvasSize.X := Round(Vec.Width * spinScale.Value);
302	306		if CanvasSize.X < Drawer.Width then CanvasSize.X := Drawer.Width;
303	307
304	308		if Vec.Height * spinScale.Value > FPVVIEWER_MAX_IMAGE_SIZE then CanvasSize.Y := FPVVIEWER_MAX_IMAGE_SIZE
305	309		else if Vec.Height < FPVVIEWER_MIN_IMAGE_SIZE then CanvasSize.Y := Drawer.Height
306	310		else CanvasSize.Y := Round(Vec.Height * spinScale.Value);
307	311		if CanvasSize.Y < Drawer.Height then CanvasSize.Y := Drawer.Height;
308	312
309	313		Drawer.Drawing.Width := CanvasSize.X;
310	314		Drawer.Drawing.Height := CanvasSize.Y;
311	315		Drawer.Drawing.Canvas.Brush.Color := clWhite;
312	316		Drawer.Drawing.Canvas.Brush.Style := bsSolid;
313	317		Drawer.Drawing.Canvas.FillRect(0, 0, Drawer.Drawing.Width, Drawer.Drawing.Height);
314	318		DrawFPVectorialToCanvas(
315	319		Vec.GetPage(0),
316	320		Drawer.Drawing.Canvas,
317	321		FPVVIEWER_SPACE_FOR_NEGATIVE_COORDS,
318	322		Drawer.Drawing.Height - FPVVIEWER_SPACE_FOR_NEGATIVE_COORDS,
319	323		spinScale.Value,
320	324		-1 * spinScale.Value);
321	325		Drawer.Invalidate;
322	326		finally
323	327		Vec.Free;
324	328		end;
325	329		end;
326	330		```
327	331
328	332		### Coordinates in FPVectorial
329	333
330	334		It is important to note that FPVectorial works with two different systems of coordinates: Top-Left Coordinates and Bottom-Left Coordinates. TCanvas uses the coordinates from the Windows API, with the origin in the top-left corner and with the X axis growing to the right and the Y axis growing to the bottom. FPVectorial, besides supporting this system, also supports another one for drawing formats where this system is native such as CAD software, Inkscape, the Mac OS X APIs (Carbon and Cocoa), etc. In FPVectorial the origin is in bottom-left for all vectorial graphics formats except SVG. The X axis grows to the right and the Y axis to the top. The origin is in the top-left for SVG and all text document formats such as DOCX.
331	335
332	336		![](/wiki-images/a/a1/Fpvectorial_coords.png)
333	337
334	338		When the coordinates do not match TCanvas, one should be careful when converting coordinates between TCanvas and FPVectorial. To convert coordinates between TCanvas and FPVectorial, one needs the height of the Canvas. The following routine from the unit fpvutils can be used to execute this conversion:
335	339
336	340		``` pascal
337	341		{@@ Converts the coordinate system from a TCanvas to FPVectorial
338	342		The basic difference is that the Y axis is positioned differently and
339	343		points upwards in FPVectorial and downwards in TCanvas.
340	344		The X axis doesn't change. The fix is trivial and requires only the Height of
341	345		the Canvas as extra info.
342	346		}
343	347		function CanvasCoordsToFPVectorial(AY: Integer; AHeight: Integer):
344	348		Integer; inline;
345	349		begin
346	350		Result := AHeight - AY;
347	351		end;
348	352		```
349	353
350	354		And there is also a difference regarding the text positioning. In TCanvas.TextOut the text is positioned based on the top-left coordinates of the text area. In fpvectorial it is based on the bottom-left. Again, there is a convenient routine in the unit fpvutils to convert between the coordinate systems:
351	355
352	356		``` pascal
353	357		{@@
354	358		LCL Text is positioned based on the top-left corner of the text.
355	359		Besides that, one also needs to take the general coordinate change into account too.
356	360
357	361		@param ACanvasHeight Should receive TCanvas.Height
358	362		@param ATextHeight Should receive TFont.Size
359	363		}
360	364		function CanvasTextPosToFPVectorial(AY: Integer; ACanvasHeight, ATextHeight: Integer): Integer;
361	365		begin
362	366		Result := CanvasCoordsToFPVectorial(AY, ACanvasHeight) - ATextHeight;
363	367		end;
364	368		```
365	369
366	370		### More examples
367	371
368	372		Since fpvectorial is part of the Lazarus distribution, you can find the examples in the folder components/fpvectorial/examples of your Lazarus directory.
369	373
370	374		## fpvviewer
371	375
372	376		The Free Pascal Vectorial Viewer is a sample application which implements a simple CAD viewer using fpvectorial.
373	377
374	378		Besides being able to visualize vectorial drawings, this software can also help in exploring the internal structure of DXF file:
375	379
376	380		![](/wiki-images/3/3d/Fpvviewer_EPS.png)![](/wiki-images/7/74/Fpvviewer.png)
377	381
378	382		Its source code can be found in the Lazarus-CCR in the directory application/fpvviewer
379	383
380	384		Link to download the zipped source snapshot of this application: <https://sourceforge.net/p/lazarus-ccr/svn/HEAD/tree/applications/fpvviewer/>
381	385
382	386		Link to download the entire Lazarus-CCR repository from subversion:
383	387
384		-	~~`svn co `[`https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr`](https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr)` lazarus-ccr`~~
	388	+	```text
	389	+	svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr lazarus-ccr
	390	+	```
385	391
386	392		### Contour line generation
387	393
388	394		fpvviewer can generate contour lines from .raw files. These files can be generated with fpv3dviewer
389	395
390	396		![](/wiki-images/c/cf/Contourlines_las.PNG)
391	397
392	398		![](/wiki-images/5/57/Contourlines_regular.PNG)
393	399
394	400		### FPVectorial Debug Tokens
395	401
396	402		FPVViewer can be utilized to see the internal debug tokens from fpvectorial, see:
397	403
398	404		![](/wiki-images/a/ae/Fpvectorial_debug_tokens.png)
399	405
400	406		## fpcorelexplorer
401	407
402	408		An application was developed for helping studying the CDR file format. At the moment this application can identify the version of CorelDraw files. It is located in fpctrunk/packages/fpvectorial/examples/fpcorelexplorer.lpi
403	409
404	410		![](/wiki-images/c/cd/Fpcorelexplorer.png)
405	411
406	412		## fpv3dviewer
407	413
408	414		One of the examples of fpvectorial located in lazarus/components/fpvectorial/examples/fpv3dviewer.lpi is a 3D viewer.
409	415
410	416		![](/wiki-images/1/1f/FPV3DViewer.png)
411	417
412	418		## Articles about fpvectorial
413	419
414	420		- Revista Clube Delphi Edition \#131: <http://www.devmedia.com.br/assgold/listmag.asp?site=3>
415	421
416	422		Go to back [[Package List\|Packages List]]
417	423
418	424		---
419	425		From the Free Pascal wiki, page "fpvectorial", as it stood on 2024-05-09 after a change by EkkehardDomning, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
420	426		Category: Data import and export
421	427		Category: FPVectorial
422	428		Category: Graphics
423	429		Category: Lazarus-CCR
424	430		Category: Packages

Back to history