[Boost-commit] svn:boost r65083 - sandbox/SOC/2007/visualization/libs/svg_plot/doc

Subject: [Boost-commit] svn:boost r65083 - sandbox/SOC/2007/visualization/libs/svg_plot/doc
From: pbristow_at_[hidden]
Date: 2010-08-28 10:49:31

Author: pbristow
Date: 2010-08-28 10:49:27 EDT (Sat, 28 Aug 2010)
New Revision: 65083
URL: http://svn.boost.org/trac/boost/changeset/65083

Log:
New section
Added:
   sandbox/SOC/2007/visualization/libs/svg_plot/doc/inkscape.qbk   (contents, props changed)

Added: sandbox/SOC/2007/visualization/libs/svg_plot/doc/inkscape.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/visualization/libs/svg_plot/doc/inkscape.qbk	2010-08-28 10:49:27 EDT (Sat, 28 Aug 2010)
@@ -0,0 +1,338 @@
+[section:inkviewscape Using Inkscape and Inkview ]
+
+These two programs can be regarded as 'reference' programs for rendering SVG images.
+The results are always superior to any general purpose browsers.
+
+[h4 Using Inkview]
+
+You may find it especially convenient to use the viewer, Inkview, on Microsoft Windows,
+and make this the default program for files of type .svg.
+To do this, you will need to download install the Inkscape package.
+Inkview.exe is included in the directory you chose for the install,
+usually C:\program Files\Inkscape.
+
+You will need to use the Windows Explorer, Tools, Folder Options,
+and add extension .svg if necessary, and then associate .svg files with inkview.exe.
+
+You may also find it convenient to add "c:\program Files\inkscape" to your Path using
+Control Panel, System, Advanced system settings, Environment variables, Path, and edit
+to append the folder.  You can then use commands like "inkview my_picture.svg" from a command window.
+
+Inkview allows one to open many svg files as a slideshow
+and move forward and backward (and back to start) with the cursor keys.
+
+This works as expected using a command window,
+for example after changing to the directory containing your SVG files,
+and running "inkview *.svg" to display all the images in the directory as a slideshow.
+
+Sadly, by default, if you select many files (but not more than 15!) in Windows Explorer,
+multiple windows are opened instead of a slideshow.
+If you know how to change this 'by design' feature, please tell me.
+
+You can use this conveniently from your desktop (for example), by creating a shortcut to inkview.exe
+(right click in the inkscape install directory and choose Create Shortcut).  Drag the shortcut to the desktop.
+Append "*.svg" to the Target, usually \c "C:\Program Files\Inkscape\inkview.exe", or perhaps the name of
+a single file.  If necessary, change Start in to the folder containing the svg files, for example,
+\c C:\Users\Paul\Desktop\My_Plots\.  You can add comment describing what it will do, and change the
+name of the shortcut file to something more helpful, for example, "View My Plots".
+
+You may instead find it useful to create a batch file, for example called view_demo_plots.bat containing, for example:
+
+  START "Inkview" /MIN inkview.exe  C:\Users\Paul\Desktop\My_Plots\*.svg
+
+that will display all the svg images in folder \My_Plots in turn as the cursor keys are pressed.
+Of course, you can also omit the folder specification, and just have `*.svg` when the location of the
+batch file will determine which svg files are being viewed.
+
+[/h4 Using Inkview]
+
+[h4 Using Inkscape to edit your plot, for example to add annotation]
+You can add text, and other graphics like lines and shape, using Inkscape.
+
+It is probably best to save as "Plain SVG" to avoid additional Inkscape specific metadata
+that will increase file size a little.
+
+Of course, if you recreate the SVG file from your C++ program, all these additions will be lost,
+but for presentations, using Inkscape may be most convenient.
+
+You can also add text and graphics to the C++ program but then you cannot see what it will
+look like immediately as you can with Inkscape.
+[/h4 Using Inkscape to edit your plot, for example to add annotation]
+
+[h4 Using Inkscape to convert your plot, for example to Portable Network Graphic png]
+
+Inkscape allows you to save in several formats:
+
+* Plain SVG - with a minimum of XML metadata.
+
+* Inkscape SVG - more XML metadata.
+
+and compressed (zipped) versions of these (producing tiny file but sadly not automatically
+unzipped by browsers, only by Inkscape and Inkview).
+
+* PostScript (.ps) and Encapsulated PostScript (.eps)
+
+* PDF via Cairo (.pdf)
+
+* Enhanced metafile (.emf)
+
+* Open document drawing (.odg)
+
+* LaTex with PSTricks macros (.text)
+
+And you can Export (all or part) as a bitmap (.bmp)
+
+And you can Import as many types including:
+
+*  Bitmap
+
+* [@www.ijg.org/ JPEG (.jpeg)]
+
+* (@en.wikipedia.org/wiki/Tagged_Image_File_Format TIFF (.tif)]
+
+* Adobe Portable document Format (.pdf)
+
+* [@www.w3.org/TR/PNG/ Portable Network Graphics (.png)]
+
+Of these, PNG is often most useful for creating Boost documentation as html, probably using Quickbook etc.
+For html, PNG is preferred because one common browser does not support SVG without an add-in.
+
+(For generating PDF, at least using RenderX, the quality of graphics using PNG is poor
+and using SVG is very much preferred).
+
+[h4 Using Inkscape to convert Scalable Vector graphic SVG files to Portable Network Graphic PNG]
+
+Unlike the GUI version, you don't get any feedback messages.
+
+so you will be surprised/disappointed/confused that
+
+  >inkscape.exe -v
+
+produces no output!
+
+(But errorlevel is set non-zero if it fails).
+
+[@http://kaioa.com/node/42 How to Use Inkscape's Command Line Options on Win32]
+
+[@http://kaioa.com/node/63 inkscapec.exe - A Command Line Wrapper for Win32]
+In a nutshell it's a tiny console application, which spawns Inkscape (with the specified arguments)
+and captures its stdout (default output) and stderr (default error output) streams and redirects it to this console.
+It also does the same with stdin for good measure.
+Its sole purpose is direct command line interaction (and determining which actions trigger GTK warnings).
+If you want to spawn Inkscape from other programs/scripts use inkscape.exe instead. For example:
+``
+  C:\Users\Paul>inkscapec.exe -V
+  Inkscape 0.46 (Apr  1 2008)
+``
+and
+[pre
+  C:\Users\Paul>inkscapec.exe -?
+  '''Usage: inkscape.exe [OPTIONS...] [FILE...]'''
+
+  Available options:
+  -V, --version                             Print the Inkscape version number (NOTE CAPITAL V).
+  -z, --without-gui                         Do not use X server (only process files from console).
+  -g, --with-gui                            Try to use X server '''(even if $DISPLAY is not set).'''
+  -f, --file=FILENAME                       Open specified document(s) (option string may be excluded).
+  -p, --print=FILENAME                      Print document(s) to specified output file (use '| program' for pipe).
+  -e, --export-png=FILENAME                 Export document to a PNG file.
+  -d, --export-dpi=DPI                      The resolution used for exporting SVG into bitmap (default 90).
+  -a, --export-area=x0:y0:x1:y1             Exported area in SVG user units (default is the canvas; 0,0 is lower-left corner).
+  -D, --export-area-drawing                 Exported area is the entire drawing (not canvas).
+  -C, --export-area-canvas                  Exported area is the entire canvas.
+      --export-area-snap                    Snap the bitmap export area outwards to the nearest integer values (in SVG user units).
+  -w, --export-width=WIDTH                  The width of exported bitmap in pixels (overrides export-dpi).
+  -h, --export-height=HEIGHT                The height of exported bitmap in pixels (overrides export-dpi).
+  -i, --export-id=ID                        The ID of the object to export.
+  -j, --export-id-only                      Export just the object with export-id, hide all others (only with export-id).
+  -t, --export-use-hints                    Use stored filename and DPI hints when exporting (only with export-id).
+  -b, --export-background=COLOR             Background color of exported bitmap (any SVG-supported color string).
+  -y, --export-background-opacity=VALUE     Background opacity of exported bitmap (either 0.0 to 1.0, or 1 to 255).
+  -l, --export-plain-svg=FILENAME           Export document to plain SVG file(no sodipodi or inkscape namespaces).
+  -P, --export-ps=FILENAME                  Export document to a PS file.
+  -E, --export-eps=FILENAME                 Export document to an EPS file.
+  -A, --export-pdf=FILENAME                 Export document to a PDF file.
+  -M, --export-emf=FILENAME                 Export document to an Enhanced Metafile (EMF) File.
+  -T, --export-text-to-path                 Convert text object to paths on export (EPS).
+  -F, --export-embed-fonts                  Embed fonts on export (Type 1 only) (EPS).
+  -B, --export-bbox-page                    Export files with the bounding box set to the page size (EPS).
+  -X, --query-x                             Query the X coordinate of the drawing or, if specified, of the object with --query-id
+  -Y, --query-y                             Query the Y coordinate of the drawing or, if specified, of the object with --query-id
+  -W, --query-width                         Query the width of the drawing or, if specified, of the object with --query-id
+  -H, --query-height                        Query the height of the drawing  or, if specified, of the object with --query-id
+  -S, --query-all                           List id,x,y,w,h for all objects.
+  -I, --query-id=ID                         The ID of the object whose dimensions are queried.
+  -x, --extension-directory                 Print out the extension directory and exit.
+  --vacuum-defs                             Remove unused definitions from the defs section(s) of the document.
+  --verb-list                               List the IDs of all the verbs in Inkscape.
+  --verb=VERB-ID                            Verb to call when Inkscape opens.
+  --select=OBJECT-ID                        Object ID to select when Inkscape opens.
+
+Help options:
+  -?, --help                                Show this help message
+  --usage                                   Display brief usage message
+] [/pre]
+
+For an interactive batch conversion using Windows at the command prompt in the svg source folder:
+``
+  X:\svg\source\folder>
+    FOR %? IN (*.svg) DO "c:\program files\inkscape\inkscape.exe" -f X:\svg\source\folder\%? -e E:\png\target\folder\%?.png
+
+    FOR \r %i IN (*.svg) DO echo %i
+``
+will list all .svg recursively in sub-folders.
+
+A batch file (for example, called svg2png1.bat) that contains either the cryptic or verbose versions:
+
+  inkscape my_plot.svg - -d 120 -e my_plot.png
+  inkscape my_plot.svg --export-png=my_plot.png --export-dpi=120
+
+converts my_plot.svg to my_plot.svg.png
+
+A batch file (for example, called svg2png.bat) containing
+
+FOR %%? IN (*.svg) DO inkscape.exe -f J:\cpp\svg\%%? -e J:\cpp\svg\%%?.png
+
+converts all the .svg file in folder J:\cpp\svg\ to .svg.png
+
+(The file type *.svg.png is useful in that it shows the fact that the original source is a SVG file).
+
+  FOR /r %%? IN (*.svg) DO inkscape.exe -f %%? -e %%?.png
+
+does the same but recursing down sub-folders, leaving the converted .png in the same folder as the oroginal .svg.
+
+  J:\Cpp\SVG>inkscape.exe -f J:\Cpp\SVG\sf_graphs\powm1.svg -e J:\Cpp\SVG\sf_graphs\powm1.svg.png
+
+Derived from [@http://inkscape.modevia.com/inkscape-man.html Examples of using Inkscape command line]
+
+[h4 Examples of using Inkscape Command line options]
+
+While obviously Inkscape is primarily intended as a GUI application,
+it can be used for doing SVG processing on the command line as well.
+
+Several of these will be useful to control the dimensions and resolution (and thus size) of exported PNG images.
+In general, PNG files are rather larger, perhaps a few times, than the original SVG file, but might be smaller
+if low enough resolution, for example for an icon.
+
+Open an SVG file in the GUI:
+
+  inkscape filename.svg
+
+Print an SVG file from the command line:
+
+  inkscape filename.svg -p '| lpr'
+
+Convert an SVG to PNG
+
+  inkscape -f file.svg -e file.png
+
+Export an SVG file into PNG with the default resolution of 90dpi
+(one SVG user unit translates to one bitmap pixel):
+
+  inkscape filename.svg --export-png=filename.png
+
+Same, but force the PNG file to be 600x400 pixels:
+
+  inkscape filename.svg --export-png=filename.png -w600 -h400
+
+Same, but export the drawing (bounding box of all objects), not the page:
+
+  inkscape filename.svg --export-png=filename.png --export-area-drawing
+
+Export to PNG the object with id="text1555", using the output filename and the resolution
+that were used for that object last time when it was exported from the GUI:
+
+  inkscape filename.svg --export-id=text1555 --export-use-hints
+
+Same, but use the default 90 dpi resolution, specify the filename,
+and snap the exported area outwards to the nearest whole SVG user unit values (to preserve pixel-alignment of objects and thus minimize aliasing):
+
+  inkscape filename.svg --export-id=text1555 --export-png=text.png --export-snap-area
+
+Convert an Inkscape SVG document to plain SVG:
+
+  inkscape filename1.svg --export-plain-svg=filename2.svg
+
+Convert an SVG document to EPS, converting all texts to paths:
+
+  inkscape filename.svg --export-eps=filename.eps --export-text-to-path
+
+Query the width of the object with id="text1555":
+
+  inkscape filename.svg --query-width --query-id text1555
+
+Duplicate the object with id="path1555", rotate the duplicate 90 degrees, save SVG, and quit:
+
+  inkscape filename.svg --select=path1555 --verb=EditDuplicate --verb=ObjectRotate90 --verb=FileSave --verb=FileClose
+
+[h4 Using Python to run Inkscape]
+
+See [@http://kaioa.com/node/42 How to Use Inkscape's Command Line Options with Python]
+
+InkCL.py (place it in the same directory as inkscape.exe)
+``
+  '''#!/opt/oss/bin/python'''
+
+  import os, subprocess, sys
+
+  def spawn():
+      cmd=sys.argv
+      cmd.pop(0)
+      cmd.insert(0,'inkscape')
+      run=subprocess.Popen(cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+      out,err=[e.splitlines() for e in run.communicate()]
+      return run.returncode, out, err
+
+  if __name__=='__main__':
+      r=spawn()
+      if not r[0]==0:
+          print 'return code:',r[0]
+      for l in r[1]:
+          print l
+      for l in r[2]:
+          print l
+  InkCL.py usage:
+  python InkCL.py <inkscape options>
+``
+  PNG export example:
+
+`` C:\Inkscape-0.45.1-1\inkscape>python InkCL.py -e image.png ext.svg
+  Background RRGGBBAA: ffffff00
+  Area 0:0:64:64 exported to 64 x 64 pixels (90 dpi)
+  Bitmap saved as: image.png
+``
+If you don't have Python installed. Fear not! Inkscape is actually shipped with a Python interpreter,
+which is used by many extensions.
+
+We can use this interpreter and also shorten the command line by using a batch file.
+
+InkCL.bat (place it in the same directory as inkscape.exe)
+
+[pre
+  '''@"./python/python.exe" InkCL.py %*'''
+
+  InkCL.bat usage:
+  InkCL.bat <inkscape options>
+  The following also works:
+  inkcl <inkscape options>
+
+PNG export example:
+
+  C:\Inkscape-0.45.1-1\inkscape>inkcl -e image.png ext.svg
+  Background RRGGBBAA: ffffff00
+  Area 0:0:64:64 exported to 64 x 64 pixels (90 dpi)
+  Bitmap saved as: image.png
+] [/pre]
+Download: inkscape_win32_command_line.zip (1kb - contains: InkCL.py, InkCL.bat, and a readme)
+
+[/h4 Using Python to run Inkscape]
+
+[endsect] [/section:inkviewscape Using Inkscape and Inkview]
+
+[/ inkscape.qbk
+  Copyright 2009 Jake Voytko and Paul A. Bristow.
+  Distributed under the Boost Software License, Version 1.0.
+  (See accompanying file LICENSE_1_0.txt or copy at
+  http://www.boost.org/LICENSE_1_0.txt).
+]
+