KiCad PCB EDA Suite
pcbplot.cpp
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr
5 * Copyright (C) 2012 SoftPLC Corporation, Dick Hollenbeck <[email protected]>
6 * Copyright (C) 1992-2022 KiCad Developers, see AUTHORS.txt for contributors.
7 *
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License
10 * as published by the Free Software Foundation; either version 2
11 * of the License, or (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, you may find one here:
20 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
21 * or you may search the http://www.gnu.org website for the version 2 license,
22 * or you may write to the Free Software Foundation, Inc.,
23 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
24 */
25
26#include <plotters/plotter.h>
27#include <pcbplot.h>
28#include <base_units.h>
29#include <locale_io.h>
30#include <reporter.h>
31#include <board.h>
33#include <plotcontroller.h>
34#include <pcb_plot_params.h>
35#include <wx/ffile.h>
36#include <dialog_plot.h>
37#include <build_version.h>
38#include <gbr_metadata.h>
39#include <render_settings.h>
40
41
42const wxString GetGerberProtelExtension( int aLayer )
43{
44 if( IsCopperLayer( aLayer ) )
45 {
46 if( aLayer == F_Cu )
47 return wxT( "gtl" );
48 else if( aLayer == B_Cu )
49 return wxT( "gbl" );
50 else
51 return wxString::Format( wxT( "g%d" ), aLayer+1 );
52 }
53 else
54 {
55 switch( aLayer )
56 {
57 case B_Adhes: return wxT( "gba" );
58 case F_Adhes: return wxT( "gta" );
59
60 case B_Paste: return wxT( "gbp" );
61 case F_Paste: return wxT( "gtp" );
62
63 case B_SilkS: return wxT( "gbo" );
64 case F_SilkS: return wxT( "gto" );
65
66 case B_Mask: return wxT( "gbs" );
67 case F_Mask: return wxT( "gts" );
68
69 case Edge_Cuts: return wxT( "gm1" );
70
71 case Dwgs_User:
72 case Cmts_User:
73 case Eco1_User:
74 case Eco2_User:
75 default: return wxT( "gbr" );
76 }
77 }
78}
79
80
81const wxString GetGerberFileFunctionAttribute( const BOARD* aBoard, int aLayer )
82{
83 wxString attrib;
84
85 switch( aLayer )
86 {
87 case F_Adhes:
88 attrib = wxT( "Glue,Top" );
89 break;
90
91 case B_Adhes:
92 attrib = wxT( "Glue,Bot" );
93 break;
94
95 case F_SilkS:
96 attrib = wxT( "Legend,Top" );
97 break;
98
99 case B_SilkS:
100 attrib = wxT( "Legend,Bot" );
101 break;
102
103 case F_Mask:
104 attrib = wxT( "Soldermask,Top" );
105 break;
106
107 case B_Mask:
108 attrib = wxT( "Soldermask,Bot" );
109 break;
110
111 case F_Paste:
112 attrib = wxT( "Paste,Top" );
113 break;
114
115 case B_Paste:
116 attrib = wxT( "Paste,Bot" );
117 break;
118
119 case Edge_Cuts:
120 // Board outline.
121 // Can be "Profile,NP" (Not Plated: usual) or "Profile,P"
122 // This last is the exception (Plated)
123 attrib = wxT( "Profile,NP" );
124 break;
125
126 case Dwgs_User:
127 attrib = wxT( "OtherDrawing,Comment" );
128 break;
129
130 case Cmts_User:
131 attrib = wxT( "Other,Comment" );
132 break;
133
134 case Eco1_User:
135 attrib = wxT( "Other,ECO1" );
136 break;
137
138 case Eco2_User:
139 attrib = wxT( "Other,ECO2" );
140 break;
141
142 case B_Fab:
143 // This is actually a assembly layer
144 attrib = wxT( "AssemblyDrawing,Bot" );
145 break;
146
147 case F_Fab:
148 // This is actually a assembly layer
149 attrib = wxT( "AssemblyDrawing,Top" );
150 break;
151
152 case B_Cu:
153 attrib.Printf( wxT( "Copper,L%d,Bot" ), aBoard->GetCopperLayerCount() );
154 break;
155
156 case F_Cu:
157 attrib = wxT( "Copper,L1,Top" );
158 break;
159
160 default:
161 if( IsCopperLayer( aLayer ) )
162 attrib.Printf( wxT( "Copper,L%d,Inr" ), aLayer+1 );
163 else
164 attrib.Printf( wxT( "Other,User" ), aLayer+1 );
165 break;
166 }
167
168 // This code adds a optional parameter: the type of copper layers.
169 // Because it is not used by Pcbnew (it can be used only by external autorouters)
170 // user do not really set this parameter.
171 // Therefore do not add it.
172 // However, this code is left here, for perhaps a future usage.
173#if 0
174 // Add the signal type of the layer, if relevant
175 if( IsCopperLayer( aLayer ) )
176 {
177 LAYER_T type = aBoard->GetLayerType( ToLAYER_ID( aLayer ) );
178
179 switch( type )
180 {
181 case LT_SIGNAL:
182 attrib += wxT( ",Signal" );
183 break;
184 case LT_POWER:
185 attrib += wxT( ",Plane" );
186 break;
187 case LT_MIXED:
188 attrib += wxT( ",Mixed" );
189 break;
190 default:
191 break; // do nothing (but avoid a warning for unhandled LAYER_T values from GCC)
192 }
193 }
194#endif
195
196 wxString fileFct;
197 fileFct.Printf( wxT( "%%TF.FileFunction,%s*%%" ), attrib );
198
199 return fileFct;
200}
201
202
203static const wxString GetGerberFilePolarityAttribute( int aLayer )
204{
205 /* build the string %TF.FilePolarity,Positive*%
206 * or %TF.FilePolarity,Negative*%
207 * an emply string for layers which do not use a polarity
208 *
209 * The value of the .FilePolarity specifies whether the image represents the
210 * presence or absence of material.
211 * This attribute can only be used when the file represents a pattern in a material layer,
212 * e.g. copper, solder mask, legend.
213 * Together with.FileFunction it defines the role of that image in
214 * the layer structure of the PCB.
215 * Note that the .FilePolarity attribute does not change the image -
216 * no attribute does.
217 * It changes the interpretation of the image.
218 * For example, in a copper layer in positive polarity a round flash generates a copper pad.
219 * In a copper layer in negative polarity it generates a clearance.
220 * Solder mask images usually represent solder mask openings and are then negative.
221 * This may be counter-intuitive.
222 */
223 int polarity = 0;
224
225 switch( aLayer )
226 {
227 case F_Adhes:
228 case B_Adhes:
229 case F_SilkS:
230 case B_SilkS:
231 case F_Paste:
232 case B_Paste:
233 polarity = 1;
234 break;
235
236 case F_Mask:
237 case B_Mask:
238 polarity = -1;
239 break;
240
241 default:
242 if( IsCopperLayer( aLayer ) )
243 polarity = 1;
244 break;
245 }
246
247 wxString filePolarity;
248
249 if( polarity == 1 )
250 filePolarity = wxT( "%TF.FilePolarity,Positive*%" );
251 if( polarity == -1 )
252 filePolarity = wxT( "%TF.FilePolarity,Negative*%" );
253
254 return filePolarity;
255}
256
257
258/* Add some X2 attributes to the file header, as defined in the
259 * Gerber file format specification J4 and "Revision 2015.06"
260 */
261
262
263// A helper function to convert a X2 attribute string to a X1 structured comment:
264static wxString& makeStringCompatX1( wxString& aText, bool aUseX1CompatibilityMode )
265{
266 if( aUseX1CompatibilityMode )
267 {
268 aText.Replace( wxT( "%" ), wxEmptyString );
269 aText.Prepend( wxT( "G04 #@! " ) );
270 }
271
272 return aText;
273}
274
275
276void AddGerberX2Header( PLOTTER* aPlotter, const BOARD* aBoard, bool aUseX1CompatibilityMode )
277{
278 wxString text;
279
280 // Creates the TF,.GenerationSoftware. Format is:
281 // %TF,.GenerationSoftware,<vendor>,<application name>[,<application version>]*%
282 text.Printf( wxT( "%%TF.GenerationSoftware,KiCad,Pcbnew,%s*%%" ), GetBuildVersion() );
283 aPlotter->AddLineToHeader( makeStringCompatX1( text, aUseX1CompatibilityMode ) );
284
285 // creates the TF.CreationDate attribute:
288 aPlotter->AddLineToHeader( text );
289
290 // Creates the TF,.ProjectId. Format is (from Gerber file format doc):
291 // %TF.ProjectId,<project id>,<project GUID>,<revision id>*%
292 // <project id> is the name of the project, restricted to basic ASCII symbols only,
293 // Rem: <project id> accepts only ASCII 7 code (only basic ASCII codes are allowed in
294 // gerber files) and comma not accepted.
295 // All illegal chars will be replaced by underscore.
296 //
297 // <project GUID> is a string which is an unique id of a project.
298 // However Kicad does not handle such a project GUID, so it is built from the board name
299 wxFileName fn = aBoard->GetFileName();
300 wxString msg = fn.GetFullName();
301
302 // Build a <project GUID>, from the board name
303 wxString guid = GbrMakeProjectGUIDfromString( msg );
304
305 // build the <project id> string: this is the board short filename (without ext)
306 // and all non ASCII chars and comma are replaced by '_'
307 msg = fn.GetName();
308 msg.Replace( wxT( "," ), wxT( "_" ) );
309
310 // build the <revision id> string. All non ASCII chars and comma are replaced by '_'
311 wxString rev = ExpandTextVars( aBoard->GetTitleBlock().GetRevision(), aBoard->GetProject() );
312 rev.Replace( wxT( "," ), wxT( "_" ) );
313
314 if( rev.IsEmpty() )
315 rev = wxT( "rev?" );
316
317 text.Printf( wxT( "%%TF.ProjectId,%s,%s,%s*%%" ), msg.ToAscii(), guid, rev.ToAscii() );
318 aPlotter->AddLineToHeader( makeStringCompatX1( text, aUseX1CompatibilityMode ) );
319
320 // Add the TF.SameCoordinates to specify that all gerber files uses the same origin and
321 // orientation, and the registration between files is OK.
322 // The parameter of TF.SameCoordinates is a string that is common to all files using the
323 // same registration. The string value has no meaning; it is just a key.
324 // Because there is no mirroring/rotation in Kicad, only the plot offset origin can create
325 // incorrect registration, so we create a key from plot offset options.
326 //
327 // Currently the key is "Original" when using absolute Pcbnew coordinates, and the PY and PY
328 // position of the auxiliary axis when using it.
329 // If we ever add user-settable absolute Pcbnew coordinates, we'll need to change the way
330 // the key is built to ensure file only using the *same* axis have the same key.
331 wxString registration_id = wxT( "Original" );
332 VECTOR2I auxOrigin = aBoard->GetDesignSettings().GetAuxOrigin();
333
334 if( aBoard->GetPlotOptions().GetUseAuxOrigin() && auxOrigin.x && auxOrigin.y )
335 registration_id.Printf( wxT( "PX%xPY%x" ), auxOrigin.x, auxOrigin.y );
336
337 text.Printf( wxT( "%%TF.SameCoordinates,%s*%%" ), registration_id.GetData() );
338 aPlotter->AddLineToHeader( makeStringCompatX1( text, aUseX1CompatibilityMode ) );
339}
340
341
342void AddGerberX2Attribute( PLOTTER* aPlotter, const BOARD* aBoard, int aLayer,
343 bool aUseX1CompatibilityMode )
344{
345 AddGerberX2Header( aPlotter, aBoard, aUseX1CompatibilityMode );
346
347 wxString text;
348
349 // Add the TF.FileFunction
350 text = GetGerberFileFunctionAttribute( aBoard, aLayer );
351 aPlotter->AddLineToHeader( makeStringCompatX1( text, aUseX1CompatibilityMode ) );
352
353 // Add the TF.FilePolarity (for layers which support that)
355
356 if( !text.IsEmpty() )
357 aPlotter->AddLineToHeader( makeStringCompatX1( text, aUseX1CompatibilityMode ) );
358}
359
360
361void BuildPlotFileName( wxFileName* aFilename, const wxString& aOutputDir,
362 const wxString& aSuffix, const wxString& aExtension )
363{
364 // aFilename contains the base filename only (without path and extension)
365 // when calling this function.
366 // It is expected to be a valid filename (this is usually the board filename)
367 aFilename->SetPath( aOutputDir );
368
369 // Set the file extension
370 aFilename->SetExt( aExtension );
371
372 // remove leading and trailing spaces if any from the suffix, if
373 // something survives add it to the name;
374 // also the suffix can contain some not allowed chars in filename (/ \ . : and some others),
375 // so change them to underscore
376 // Remember it can be called from a python script, so the illegal chars
377 // have to be filtered here.
378 wxString suffix = aSuffix;
379 suffix.Trim( true );
380 suffix.Trim( false );
381
382 wxString badchars = wxFileName::GetForbiddenChars(wxPATH_DOS);
383 badchars.Append( "%." );
384
385 for( unsigned ii = 0; ii < badchars.Len(); ii++ )
386 suffix.Replace( badchars[ii], wxT("_") );
387
388 if( !suffix.IsEmpty() )
389 aFilename->SetName( aFilename->GetName() + wxT( "-" ) + suffix );
390}
391
392
394{
395 m_plotter = nullptr;
396 m_board = aBoard;
398}
399
400
402{
403 ClosePlot();
404}
405
406
407/*
408 * IMPORTANT: the locale during plots *MUST* be kept as C/POSIX using a LOCALE_IO object on the
409 * stack. This even when opening/closing the plotfile, as some drivers do I/O even then.
410 */
412{
413 LOCALE_IO toggle;
414
415 if( m_plotter )
416 {
418
419 delete m_plotter->RenderSettings();
420 delete m_plotter;
421
422 m_plotter = nullptr;
423 }
424}
425
426
427bool PLOT_CONTROLLER::OpenPlotfile( const wxString& aSuffix, PLOT_FORMAT aFormat,
428 const wxString& aSheetName, const wxString& aSheetPath )
429{
430 LOCALE_IO toggle;
431
432 // Save the current format: sadly some plot routines depends on this but the main reason
433 // is that the StartPlot method uses it to dispatch the plotter creation
434 GetPlotOptions().SetFormat( aFormat );
435
436 // Ensure that the previous plot is closed
437 ClosePlot();
438
439 // Now compute the full filename for the output and start the plot (after ensuring the
440 // output directory is OK).
441
442 std::function<bool( wxString* )> textResolver =
443 [&]( wxString* token ) -> bool
444 {
445 // Handles m_board->GetTitleBlock() *and* m_board->GetProject()
446 return m_board->ResolveTextVar( token, 0 );
447 };
448
449 wxString outputDirName = GetPlotOptions().GetOutputDirectory();
450 outputDirName = ExpandTextVars( outputDirName, &textResolver, nullptr, nullptr );
451 outputDirName = ExpandEnvVarSubstitutions( outputDirName, nullptr );
452
453 wxFileName outputDir = wxFileName::DirName( outputDirName );
454 wxString boardFilename = m_board->GetFileName();
455
456 if( EnsureFileDirectoryExists( &outputDir, boardFilename ) )
457 {
458 // outputDir contains now the full path of plot files
459 m_plotFile = boardFilename;
460 m_plotFile.SetPath( outputDir.GetPath() );
461 wxString fileExt = GetDefaultPlotExtension( aFormat );
462
463 // Gerber format *can* use layer-specific file extensions (this is no longer best
464 // practice as the official file ext is now .gbr).
465 if( GetPlotOptions().GetFormat() == PLOT_FORMAT::GERBER
466 && GetPlotOptions().GetUseGerberProtelExtensions() )
467 {
468 fileExt = GetGerberProtelExtension( GetLayer() );
469 }
470
471 // Build plot filenames from the board name and layer names:
472 BuildPlotFileName( &m_plotFile, outputDir.GetPath(), aSuffix, fileExt );
473
475 m_plotFile.GetFullPath(), aSheetName, aSheetPath );
476 }
477
478 return ( m_plotter != nullptr );
479}
480
481
483{
484 LOCALE_IO toggle;
485
486 // No plot open, nothing to do...
487 if( !m_plotter )
488 return false;
489
490 // Fully delegated to the parent
492
493 return true;
494}
495
496
497void PLOT_CONTROLLER::SetColorMode( bool aColorMode )
498{
499 if( !m_plotter )
500 return;
501
502 m_plotter->SetColorMode( aColorMode );
503}
504
505
507{
508 if( !m_plotter )
509 return false;
510
511 return m_plotter->GetColorMode();
512}
LAYER_T
The allowed types of layers, same as Specctra DSN spec.
Definition: board.h:143
@ LT_POWER
Definition: board.h:146
@ LT_MIXED
Definition: board.h:147
@ LT_SIGNAL
Definition: board.h:145
wxString GetBuildVersion()
Get the full KiCad version string.
const VECTOR2I & GetAuxOrigin()
Information pertinent to a Pcbnew printed circuit board.
Definition: board.h:265
LAYER_T GetLayerType(PCB_LAYER_ID aLayer) const
Return the type of the copper layer given by aLayer.
Definition: board.cpp:447
bool ResolveTextVar(wxString *token, int aDepth) const
Definition: board.cpp:310
TITLE_BLOCK & GetTitleBlock()
Definition: board.h:632
int GetCopperLayerCount() const
Definition: board.cpp:502
const wxString & GetFileName() const
Definition: board.h:302
const PCB_PLOT_PARAMS & GetPlotOptions() const
Definition: board.h:629
PROJECT * GetProject() const
Definition: board.h:440
BOARD_DESIGN_SETTINGS & GetDesignSettings() const
Definition: board.cpp:643
Instantiate the current locale within a scope in which you are expecting exceptions to be thrown.
Definition: locale_io.h:41
bool GetUseAuxOrigin() const
wxString GetOutputDirectory() const
void SetFormat(PLOT_FORMAT aFormat)
Base plotter engine class.
Definition: plotter.h:110
virtual bool EndPlot()=0
RENDER_SETTINGS * RenderSettings()
Definition: plotter.h:141
bool GetColorMode() const
Definition: plotter.h:138
void AddLineToHeader(const wxString &aExtraString)
Add a line to the list of free lines to print at the beginning of the file.
Definition: plotter.h:168
virtual void SetColorMode(bool aColorMode)
Plot in B/W or color.
Definition: plotter.h:137
~PLOT_CONTROLLER()
Ensure that the last plot is closed.
Definition: pcbplot.cpp:401
bool GetColorMode()
Definition: pcbplot.cpp:506
wxFileName m_plotFile
bool PlotLayer()
Plot a single layer on the current plotfile m_plotLayer is the layer to plot.
Definition: pcbplot.cpp:482
PLOT_CONTROLLER(BOARD *aBoard)
Batch plotter constructor, nothing interesting here.
Definition: pcbplot.cpp:393
void SetColorMode(bool aColorMode)
Choose color or bland and white plot mode.
Definition: pcbplot.cpp:497
bool OpenPlotfile(const wxString &aSuffix, PLOT_FORMAT aFormat, const wxString &aSheetName=wxEmptyString, const wxString &aSheetPath=wxEmptyString)
Open a new plotfile; works as a factory for plotter objects/.
Definition: pcbplot.cpp:427
PLOTTER * m_plotter
This is the plotter object; it starts NULL and become instantiated when a plotfile is.
PCB_PLOT_PARAMS & GetPlotOptions()
Accessor to the plot parameters and options.
void ClosePlot()
Close the current plot, nothing happens if it isn't open.
Definition: pcbplot.cpp:411
const wxString & GetRevision() const
Definition: title_block.h:86
const wxString ExpandEnvVarSubstitutions(const wxString &aString, const PROJECT *aProject)
Replace any environment variable & text variable references with their values.
Definition: common.cpp:267
bool EnsureFileDirectoryExists(wxFileName *aTargetFullFileName, const wxString &aBaseFilename, REPORTER *aReporter)
Make aTargetFullFileName absolute and create the path of this file if it doesn't yet exist.
Definition: common.cpp:295
wxString ExpandTextVars(const wxString &aSource, const PROJECT *aProject)
Definition: common.cpp:57
wxString GetDefaultPlotExtension(PLOT_FORMAT aFormat)
Returns the default plot extension for a format.
wxString GbrMakeProjectGUIDfromString(const wxString &aText)
Build a project GUID using format RFC4122 Version 1 or 4 from the project name, because a KiCad proje...
wxString GbrMakeCreationDateAttributeString(GBR_NC_STRING_FORMAT aFormat)
Handle special data (items attributes) during plot.
@ GBR_NC_STRING_FORMAT_X1
Definition: gbr_metadata.h:61
@ GBR_NC_STRING_FORMAT_X2
Definition: gbr_metadata.h:62
bool IsCopperLayer(int aLayerId)
Tests whether a layer is a copper layer.
Definition: layer_ids.h:825
@ B_Adhes
Definition: layer_ids.h:97
@ Edge_Cuts
Definition: layer_ids.h:113
@ Dwgs_User
Definition: layer_ids.h:109
@ F_Paste
Definition: layer_ids.h:101
@ Cmts_User
Definition: layer_ids.h:110
@ F_Adhes
Definition: layer_ids.h:98
@ B_Mask
Definition: layer_ids.h:106
@ B_Cu
Definition: layer_ids.h:95
@ Eco1_User
Definition: layer_ids.h:111
@ F_Mask
Definition: layer_ids.h:107
@ B_Paste
Definition: layer_ids.h:100
@ F_Fab
Definition: layer_ids.h:120
@ F_SilkS
Definition: layer_ids.h:104
@ UNDEFINED_LAYER
Definition: layer_ids.h:60
@ Eco2_User
Definition: layer_ids.h:112
@ B_SilkS
Definition: layer_ids.h:103
@ F_Cu
Definition: layer_ids.h:64
@ B_Fab
Definition: layer_ids.h:119
PCB_LAYER_ID ToLAYER_ID(int aLayer)
Definition: lset.cpp:932
const wxString GetGerberProtelExtension(int aLayer)
Definition: pcbplot.cpp:42
static wxString & makeStringCompatX1(wxString &aText, bool aUseX1CompatibilityMode)
Definition: pcbplot.cpp:264
void AddGerberX2Header(PLOTTER *aPlotter, const BOARD *aBoard, bool aUseX1CompatibilityMode)
Calculate some X2 attributes as defined in the Gerber file format specification J4 (chapter 5) and ad...
Definition: pcbplot.cpp:276
const wxString GetGerberFileFunctionAttribute(const BOARD *aBoard, int aLayer)
Return the "file function" attribute for aLayer, as defined in the Gerber file format specification J...
Definition: pcbplot.cpp:81
void AddGerberX2Attribute(PLOTTER *aPlotter, const BOARD *aBoard, int aLayer, bool aUseX1CompatibilityMode)
Calculate some X2 attributes as defined in the Gerber file format specification and add them to the g...
Definition: pcbplot.cpp:342
void BuildPlotFileName(wxFileName *aFilename, const wxString &aOutputDir, const wxString &aSuffix, const wxString &aExtension)
Complete a plot filename.
Definition: pcbplot.cpp:361
static const wxString GetGerberFilePolarityAttribute(int aLayer)
Definition: pcbplot.cpp:203
void PlotOneBoardLayer(BOARD *aBoard, PLOTTER *aPlotter, PCB_LAYER_ID aLayer, const PCB_PLOT_PARAMS &aPlotOpt)
Plot one copper or technical layer.
PLOTTER * StartPlotBoard(BOARD *aBoard, const PCB_PLOT_PARAMS *aPlotOpts, int aLayer, const wxString &aFullFileName, const wxString &aSheetName, const wxString &aSheetPath)
Open a new plotfile using the options (and especially the format) specified in the options and prepar...
Plot settings, and plotting engines (PostScript, Gerber, HPGL and DXF)
PLOT_FORMAT
The set of supported output plot formats.
Definition: plotter.h:70
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, const CPTREE &aTree)
Output a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:200