Add a python script example in demo folder to create various plot files from a board. Fix also some issues in plot controller helper class.

Important note: from a python script one cannot plot the palge layout, because the page layout template file is not stored in the board file, but it is part of the project.
Because when using a python script, the project is not loaded, the page layout template is not known.
Trying to plot it crashes the script.

demos/CMakeLists.txt

@@ -1,7 +1,15 @@
-install( DIRECTORY complex_hierarchy
-    ecc83 electric flat_hierarchy
-    kit-dev-coldfire-xilinx_5213 interf_u microwave
-    pic_programmer pspice "sonde xilinx" test_xil_95108 video
+install( DIRECTORY
+    complex_hierarchy
+    ecc83 electric
+    flat_hierarchy
+    interf_u
+    kit-dev-coldfire-xilinx_5213
+    microwave
+    pic_programmer pspice
+    python_scripts_examples
+    "sonde xilinx"
+    test_pads_inside_pads
+    test_xil_95108 video
     DESTINATION ${KICAD_DEMOS}
     COMPONENT resources
     )

demos/python_scripts_examples/plot_board.py

@@ -0,0 +1,211 @@
+'''
+    A python script example to create various plot files from a board:
+    Fab files
+    Doc files
+    Gerber files
+
+    Important note:
+        this python script does not plot frame references.
+        the reason is it is not yet possible from a python script because plotting
+        plot frame references needs loading the corresponding page layout file
+        (.wks file) or the default template.
+
+        This info (the page layout template) is not stored in the board, and therefore
+        not available.
+
+        Do not try to change SetPlotFrameRef(False) to SetPlotFrameRef(true)
+        the result is the pcbnew lib will crash if you try to plot
+        the unknown frame references template.
+'''
+
+import sys
+
+from pcbnew import *
+filename=sys.argv[1]
+
+board = LoadBoard(filename)
+
+pctl = PLOT_CONTROLLER(board)
+
+popt = pctl.GetPlotOptions()
+
+popt.SetOutputDirectory("plot/")
+
+# Set some important plot options:
+popt.SetPlotFrameRef(False)
+popt.SetLineWidth(FromMM(0.35))
+
+popt.SetAutoScale(False)
+popt.SetScale(1)
+popt.SetMirror(False)
+popt.SetUseGerberAttributes(True)
+popt.SetExcludeEdgeLayer(False);
+popt.SetScale(1)
+popt.SetUseAuxOrigin(True)
+
+# This by gerbers only (also the name is truly horrid!)
+popt.SetSubtractMaskFromSilk(False)
+
+pctl.SetLayer(F_SilkS)
+pctl.OpenPlotfile("Silk", PLOT_FORMAT_PDF, "Assembly guide")
+pctl.PlotLayer()
+
+# Once the defaults are set it become pretty easy...
+# I have a Turing-complete programming language here: I'll use it...
+# param 0 is a string added to the file base name to identify the drawing
+# param 1 is the layer ID
+plot_plan = [
+    ( "CuTop", F_Cu, "Top layer" ),
+    ( "CuBottom", B_Cu, "Bottom layer" ),
+    ( "PasteBottom", B_Paste, "Paste Bottom" ),
+    ( "PasteTop", F_Paste, "Paste top" ),
+    ( "SilkTop", F_SilkS, "Silk top" ),
+    ( "SilkBottom", B_SilkS, "Silk top" ),
+    ( "MaskBottom", B_Mask, "Mask bottom" ),
+    ( "MaskTop", F_Mask, "Mask top" ),
+    ( "EdgeCuts", Edge_Cuts, "Edges" ),
+]
+
+
+for layer_info in plot_plan:
+    pctl.SetLayer(layer_info[1])
+    pctl.OpenPlotfile(layer_info[0], PLOT_FORMAT_GERBER, layer_info[2])
+    pctl.PlotLayer()
+
+# Our fabricators want two additional gerbers:
+# An assembly with no silk trim and all and only the references
+# (you'll see that even holes have designators, obviously)
+popt.SetSubtractMaskFromSilk(False)
+popt.SetPlotReference(True)
+popt.SetPlotValue(False)
+popt.SetPlotInvisibleText(True)
+
+pctl.SetLayer(F_SilkS)
+pctl.OpenPlotfile("AssyTop", PLOT_FORMAT_PDF, "Assembly top")
+pctl.PlotLayer()
+
+# And a gerber with only the component outlines (really!)
+popt.SetPlotReference(False)
+popt.SetPlotInvisibleText(False)
+pctl.SetLayer(F_SilkS)
+pctl.OpenPlotfile("AssyOutlinesTop", PLOT_FORMAT_PDF, "Assembly outline top")
+pctl.PlotLayer()
+
+# The same could be done for the bottom side, if there were components
+popt.SetUseAuxOrigin(False)
+
+## For documentation we also want a general layout PDF
+## I usually use a shell script to merge the ps files and then distill the result
+## Now I can do it with a control file. As a bonus I can have references in a
+## different colour, too.
+
+popt.SetPlotReference(True)
+popt.SetPlotValue(True)
+popt.SetPlotInvisibleText(False)
+# Remember that the frame is always in color 0 (BLACK) and should be requested
+# before opening the plot
+popt.SetPlotFrameRef(False)
+pctl.SetLayer(Dwgs_User)
+
+pctl.OpenPlotfile("Layout", PLOT_FORMAT_PDF, "General layout")
+pctl.PlotLayer()
+
+# Do the PCB edges in yellow
+popt.SetColor(YELLOW)
+pctl.SetLayer(Edge_Cuts)
+pctl.PlotLayer()
+
+## Comments in, uhmm... green
+popt.SetColor(GREEN)
+pctl.SetLayer(Cmts_User)
+pctl.PlotLayer()
+
+# Bottom mask as lines only, in red
+#popt.SetMode(LINE)
+popt.SetColor(RED)
+pctl.SetLayer(B_Mask)
+pctl.PlotLayer()
+
+# Top mask as lines only, in blue
+popt.SetColor(BLUE)
+pctl.SetLayer(F_Mask)
+pctl.PlotLayer()
+
+# Top paste in light blue, filled
+popt.SetColor(BLUE)
+#popt.SetMode(FILLED)
+pctl.SetLayer(F_Paste)
+pctl.PlotLayer()
+
+# Top Silk in cyan, filled, references in dark cyan
+popt.SetReferenceColor(DARKCYAN)
+popt.SetColor(CYAN)
+pctl.SetLayer(F_SilkS)
+pctl.PlotLayer()
+
+popt.SetTextMode(PLOTTEXTMODE_STROKE)
+pctl.SetLayer(F_Mask)
+pctl.OpenPlotfile("Assembly", PLOT_FORMAT_SVG, "Master Assembly")
+pctl.SetColorMode(True)
+
+# We want *everything*
+popt.SetPlotReference(True)
+popt.SetPlotValue(True)
+popt.SetPlotInvisibleText(True)
+
+# Remember than the DXF driver assigns colours to layers. This means that
+# we will be able to turn references on and off simply using their layers
+# Also most of the layer are now plotted in 'line' mode, because DXF handles
+# fill mode almost like sketch mode (this is to keep compatibility with
+# most CAD programs; most of the advanced primitive attributes required are
+# handled only by recent autocads...); also the entry level cads (qcad
+# and derivatives) simply don't handle polyline widths...
+
+# Here I'm using numbers for colors and layers, I'm too lazy too look them up:P
+popt.SetReferenceColor(19)
+popt.SetValueColor(21)
+
+popt.SetColor(0)
+#popt.SetMode(LINE)
+pctl.SetLayer(B_SilkS)
+pctl.PlotLayer()
+popt.SetColor(14)
+pctl.SetLayer(F_SilkS)
+pctl.PlotLayer()
+popt.SetColor(2)
+pctl.SetLayer(B_Mask)
+pctl.PlotLayer()
+popt.SetColor(4)
+pctl.SetLayer(F_Mask)
+pctl.PlotLayer()
+popt.SetColor(1)
+pctl.SetLayer(B_Paste)
+pctl.PlotLayer()
+popt.SetColor(9)
+pctl.SetLayer(F_Paste)
+pctl.PlotLayer()
+popt.SetColor(3)
+pctl.SetLayer(Edge_Cuts)
+pctl.PlotLayer()
+
+# Export the copper layers too... exporting one of them in filled mode with
+# drill marks will put the marks in the WHITE later (since it tries to blank
+# the pads...); these will be obviously great reference points for snap
+# and stuff in the cad. A pctl function to only plot them would be
+# better anyway...
+
+popt.SetColor(17)
+#popt.SetMode(FILLED)
+popt.SetDrillMarksType(PCB_PLOT_PARAMS.FULL_DRILL_SHAPE)
+pctl.SetLayer(B_Cu)
+pctl.PlotLayer()
+popt.SetColor(20)
+popt.SetDrillMarksType(PCB_PLOT_PARAMS.NO_DRILL_SHAPE)
+pctl.SetLayer(F_Cu)
+pctl.PlotLayer()
+
+# At the end you have to close the last plot, otherwise you don't know when
+# the object will be recycled!
+pctl.ClosePlot()
+
+# We have just generated 21 plotfiles with a single script

pcbnew/pcbplot.cpp

@@ -314,8 +314,10 @@ void BuildPlotFileName( wxFileName*     aFilename,
 
 
 PLOT_CONTROLLER::PLOT_CONTROLLER( BOARD *aBoard )
-    : m_plotter( NULL ), m_board( aBoard )
 {
+    m_plotter = NULL;
+    m_board = aBoard;
+    m_plotLayer = UNDEFINED_LAYER;
 }
 
 
@@ -351,14 +353,14 @@ bool PLOT_CONTROLLER::OpenPlotfile( const wxString &aSuffix,
     /* Save the current format: sadly some plot routines depends on this
        but the main reason is that the StartPlot method uses it to
        dispatch the plotter creation */
-    m_plotOpts.SetFormat( aFormat );
+    GetPlotOptions().SetFormat( aFormat );
 
     // Ensure that the previous plot is closed
     ClosePlot();
 
     // Now compute the full filename for the output and start the plot
     // (after ensuring the output directory is OK)
-    wxString outputDirName = m_plotOpts.GetOutputDirectory() ;
+    wxString outputDirName = GetPlotOptions().GetOutputDirectory() ;
     wxFileName outputDir = wxFileName::DirName( outputDirName );
     wxString boardFilename = m_board->GetFileName();
 
@@ -367,14 +369,14 @@ bool PLOT_CONTROLLER::OpenPlotfile( const wxString &aSuffix,
         wxFileName fn( boardFilename );
         BuildPlotFileName( &fn, outputDirName, aSuffix, GetDefaultPlotExtension( aFormat ) );
 
-        m_plotter = StartPlotBoard( m_board, &m_plotOpts, UNDEFINED_LAYER, fn.GetFullPath(), aSheetDesc );
+        m_plotter = StartPlotBoard( m_board, &GetPlotOptions(), ToLAYER_ID( GetLayer() ), fn.GetFullPath(), aSheetDesc );
     }
 
     return( m_plotter != NULL );
 }
 
 
-bool PLOT_CONTROLLER::PlotLayer( LAYER_NUM aLayer )
+bool PLOT_CONTROLLER::PlotLayer()
 {
     LOCALE_IO toggle;
 
@@ -383,7 +385,7 @@ bool PLOT_CONTROLLER::PlotLayer( LAYER_NUM aLayer )
         return false;
 
     // Fully delegated to the parent
-    PlotOneBoardLayer( m_board, m_plotter, ToLAYER_ID( aLayer ), m_plotOpts );
+    PlotOneBoardLayer( m_board, m_plotter, ToLAYER_ID( GetLayer() ), GetPlotOptions() );
 
     return true;
 }

pcbnew/plotcontroller.h

@@ -34,7 +34,6 @@
 
 class PLOTTER;
 class BOARD;
-class REPORTER;
 
 
 /**
@@ -47,29 +46,51 @@ public:
     /** Batch plotter constructor, nothing interesting here */
     PLOT_CONTROLLER( BOARD *aBoard );
 
-    /** Batch plotter destructor, ensures that the last plot is closed */
+    /** Batch plotter destructor, ensures that the last plot is closed
+     */
     ~PLOT_CONTROLLER();
 
-    PCB_PLOT_PARAMS *AccessPlotOpts() { return &m_plotOpts; }
+    /**
+     * Accessor to the plot parameters and options
+     */
+    PCB_PLOT_PARAMS& GetPlotOptions() { return m_plotOptions; }
+
+    void SetLayer( LAYER_NUM aLayer ) { m_plotLayer = aLayer; }
+    LAYER_NUM GetLayer() { return m_plotLayer; }
+
+
+    /**
+     * @return true if a plotter is initialized and can be used
+     */
     bool IsPlotOpen() const { return m_plotter != NULL; }
 
-    /** Close the current plot, nothing happens if it isn't open */
+    /** Close the current plot, nothing happens if it isn't open
+     */
     void ClosePlot();
 
     /** Open a new plotfile; works as a factory for plotter objects
+     * @param aSuffix is a string added to the base filename (derived from
+     * the board filename) to identify the plot file
+     * @param aFormat is the plot file format identifier
+     * @param aSheetDesc
      */
     bool OpenPlotfile( const wxString &aSuffix, PlotFormat aFormat,
                        const wxString &aSheetDesc );
 
-    /** Plot a single layer on the current plotfile */
-    bool PlotLayer( LAYER_NUM layer );
+    /** Plot a single layer on the current plotfile
+     * m_plotLayer is the layer to plot
+     */
+    bool PlotLayer();
 
     void SetColorMode( bool aColorMode );
     bool GetColorMode();
 
 private:
+    /// the layer to plot
+    LAYER_NUM m_plotLayer;
+
     /// Option bank
-    PCB_PLOT_PARAMS m_plotOpts;
+    PCB_PLOT_PARAMS m_plotOptions;
 
     /// This is the plotter object; it starts NULL and become instantiated
     /// when a plotfile is requested