SoVectorizeAction Class Reference
[HardCopy]

HardCopy Abstract class for vectorizing a scene graph to a file. More...

#include <HardCopy/SoVectorizeAction.h>

Inheritance diagram for SoVectorizeAction:
SoAction SoTypedObject SoVectorizeCGMAction SoVectorizeGDIAction SoVectorizeHPGLAction SoVectorizePSAction

List of all members.

Public Types

enum  DimensionUnit {
  INCH,
  MM,
  METER
}
enum  ShadeModel {
  FLAT,
  SMOOTH
}
enum  Orientation {
  PORTRAIT,
  LANDSCAPE
}
enum  ColorTranslationMethod {
  REVERSE_ONLY_BLACK_AND_WHITE,
  AS_IS,
  REVERSE
}
enum  JoinLineStyle {
  NO_JOIN,
  MITERED_JOIN,
  MITERED_BEVELED_JOIN,
  BEVELED_JOIN,
  TRIANGULAR_JOIN,
  ROUNDED_JOIN
}
enum  EndLineStyle {
  BUTT_END,
  SQUARE_END,
  TRIANGULAR_END,
  ROUND_END
}
enum  HLHSRMode {
  NO_HLHSR,
  HLHSR_SIMPLE_PAINTER,
  HLHSR_PAINTER,
  HLHSR_PAINTER_SURFACE_REMOVAL,
  HLHSR_RASTER,
  HIDDEN_LINES_REMOVAL
}

Public Member Functions

virtual SoType getTypeId () const
virtual ~SoVectorizeAction ()
virtual SoVectorOutputgetVectorOutput () const
virtual void apply (SoNode *node)
virtual void apply (SoPath *path)
virtual void apply (const SoPathList &pathList, SbBool obeysRules=FALSE)
virtual void beginPage (const SbVec2f &startPagePosition, const SbVec2f &pageSize, DimensionUnit u=MM)
virtual void endPage ()
virtual void setDrawingDimensions (float w, float h, DimensionUnit u=MM)
virtual void setDrawingDimensions (const SbVec2f &d, DimensionUnit u=MM)
virtual SbVec2f getDrawingDimensions (DimensionUnit u=MM) const
virtual void setStartPosition (float x, float y, DimensionUnit u=MM)
virtual void setStartPosition (const SbVec2f &p, DimensionUnit u=MM)
virtual SbVec2f getStartPosition (DimensionUnit u=MM) const
virtual void setOrientation (Orientation o)
virtual Orientation getOrientation () const
virtual void setBorder (float width)
virtual void setBorder (float width, SbColor color)
virtual void getBorder (float *w, SbColor *color) const
virtual void setBackgroundColor (SbBool bg)
virtual void setBackgroundColor (SbBool bg, SbColor color)
virtual SbBool getBackgroundColor (SbColor *color) const
virtual void setNominalWidth (float w, DimensionUnit u=MM)
virtual float getNominalWidth (DimensionUnit u=MM) const
virtual void setLinePatternSize (float w, DimensionUnit u=MM)
virtual float getLinePatternSize (DimensionUnit u=MM) const
virtual void setPixelImageSize (float w, DimensionUnit u=MM)
virtual float getPixelImageSize (DimensionUnit u=MM) const
virtual void setColorTranslationMethod (ColorTranslationMethod method)
virtual ColorTranslationMethod getColorTranslationMethod () const
virtual void setLineEndStyle (EndLineStyle style)
virtual EndLineStyle getLineEndStyle () const
virtual void setLineJoinsStyle (JoinLineStyle style)
virtual JoinLineStyle getLineJoinsStyle () const
virtual void setMiterLimit (float limit)
virtual float getMiterLimit () const
virtual void setPenDescription (int num_pens, const SbColor *colors=0, const float *widths=0, DimensionUnit u=MM)
virtual void getPenDescription (SbColor *colors, float *widths, DimensionUnit u=MM) const
virtual int getPenNum () const
virtual void setColorPriority (SbBool priority)
virtual SbBool getColorPriority (void) const
virtual void setHLHSRMode (HLHSRMode mode)
HLHSRMode getHLHSRMode () const
virtual void enableLighting (SbBool flag)
SbBool isLightingEnabled () const
void setShadeModel (ShadeModel model)
ShadeModel getShadeModel ()
void setPolygonOffset (float offset)
void setLineOffset (float offset)
void setMarkerOffset (float offset)
float getPolygonOffset () const
float getLineOffset () const
float getMarkerOffset () const

Static Public Member Functions

static SoType getClassTypeId ()

Friends

class SoHLHSRVectorize
class SoHLHSRImageVectorizer



void setHLHSRRasterQuality (float quality)
float getHLHSRRasterQuality () const
void setHLHSRRasterCaching (SbBool enable)
SbBool getHLHSRRasterCaching () const

Detailed Description

HardCopy Abstract class for vectorizing a scene graph to a file.

This class is an abstract class for all vectorize actions. The supported subclasses are SoVectorizeCGMAction, SoVectorizeGDIAction (Win32 only), SoVectorizeHPGLAction, and SoVectorizePSAction. As with SoWriteAction, these subclasses contain an SoVectorOutput instance (or derived) which writes by default to standard output. Methods on SoVectorOutput can be called to specify what file to write to.

Default values:

Line end styles description:

SoVectorizeAction.gif

Force black and white rendering:
It is possible to force black and white rendering by setting the environment variable OIV_HC_BLACK_AND_WHITE (see SoPreferences). In this mode all non-white colors are set to full black. This is useful because selecting "black & white" in the printer setup dialog normally produces gray scale rendering and some colors may be difficult to see. This option is applied after color translation (e.g. REVERSE_ONLY_BLACK_AND_WHITE). The variable must be set before creating an instance of the class.

Performance:
The HLHSR modes NO_HLHSR and HLHSR_SIMPLE_PAINTER are generally quite fast and should be used whenever possible (when the resulting image quality is acceptable or when a quick preview is desired). The other HLHSR modes involve computations that are very CPU intensive. In other words, the time required to produce an image depends almost entirely on the machine's processor speed. HLHSR_PAINTER_SURFACE_REMOVAL has a very small dependency on the graphics board (because it does one offscreen render) whereas HLHSR_RASTER performance is completely linked to the graphics board performance. The other modes are not affected by the graphics board performance. One implication of the CPU dependency is that the release libraries will generally be much faster than the debug libraries (because of compiler optimizations). Benchmarking should always be done using the release libraries.

Performance is directly related to the number of primitives (individual faces and line segments, not the number of nodes in the scene graph) and the number of intersecting or difficult-to-sort primitives. Performance decreases rapidly (worse than linear) for large numbers of primitives. Therefore algorithms that can reduce the number of primitives may be needed for large scenes (see, for example, SoSimplifyAction).

In some cases setting a small polygon offset can improve performance by reducing interference between faces and lines (used only with the Painter's algorithm HLHSR modes).

HIDDEN_LINES_REMOVAL mode is very slow and should not be used unless very precise output is required.

Generally HLHSR_RASTER mode gives the best combination of performance and image quality.

Limitations


Member Enumeration Documentation

Color translation methods.

Enumerator:
REVERSE_ONLY_BLACK_AND_WHITE 

Only black and white are reversed (default).

AS_IS 

Colors stay as is.

REVERSE 

All colors are reversed.

Dimension unit.

Enumerator:
INCH 

Inch.

MM 

Millimeter.

METER 

Meter.

End line style.

Enumerator:
BUTT_END 
SQUARE_END 
TRIANGULAR_END 
ROUND_END 

HLHSR (Hidden Line and Hidden Surface Removal) mode.

For additional info, see setHLHSRMode.

Enumerator:
NO_HLHSR 

No HLHSR is done.

HLHSR_SIMPLE_PAINTER 

Simple painter's algorithm is used.

HLHSR_PAINTER 

Painter's algorithm is used.

Interpenetrating primitives are split to provide more correct visual results.

HLHSR_PAINTER_SURFACE_REMOVAL 

Surfaces that are completely hidden are removed prior to application of the painter's algorithm.

HLHSR_RASTER 

A raster-based algorithm is used.

HIDDEN_LINES_REMOVAL 

The output is rendered with lines (regardless of the on-screen render style) and hidden lines are removed.

Join line style.

Enumerator:
NO_JOIN 

There is no line join style.

MITERED_JOIN 

The line join style is mitered.

MITERED_BEVELED_JOIN 

The line join style is mitered and beveled.

BEVELED_JOIN 

The line join style is beveled.

TRIANGULAR_JOIN 

The line join style is triangular.

ROUNDED_JOIN 

The line join style is rounded.

Orientation type.

Enumerator:
PORTRAIT 

The orientation is PORTRAIT.

LANDSCAPE 

The orientation is LANDSCAPE.

Shading models.

Enumerator:
FLAT 

Flat shading model.

Each polygon is filled with a unique color which is the average of the colors associated with each vertex of the original polygon.

SMOOTH 

Smooth shading model.

Each polygon is filled with shaded colors which are interpolations of of the colors associated with each vertex of the original polygon. NOTE: Only supported with PostScript Level 3 format.


Constructor & Destructor Documentation

virtual SoVectorizeAction::~SoVectorizeAction (  )  [virtual]

Member Function Documentation

virtual void SoVectorizeAction::apply ( const SoPathList pathList,
SbBool  obeysRules = FALSE 
) [virtual]

Initiates an action on the graph specified by list of paths.

TRUE can be passed for the obeysRules flag if the given path list has the following four properties:

  • All paths have the same head node,
  • Paths are sorted in traversal order,
  • If one path ends at node A, no other path continues through A,
  • No two paths are the same.

These rules will be obeyed by path lists returned by picking and by searches for non-group nodes.

Reimplemented from SoAction.

virtual void SoVectorizeAction::apply ( SoPath path  )  [virtual]

Initiates an action on the graph specified by a path.

Reimplemented from SoAction.

virtual void SoVectorizeAction::apply ( SoNode node  )  [virtual]

Initiates an action on the graph specified by a node.

Reimplemented from SoAction.

virtual void SoVectorizeAction::beginPage ( const SbVec2f startPagePosition,
const SbVec2f pageSize,
DimensionUnit  u = MM 
) [virtual]

Begin a new page.

Allows the user to generate multiple plots per page. A typical use is:

   SoVectorizePSAction vectPS;
   vectPS.beginPage(startPos, pageSize);

   // Draw the scene graph root1 from the start point
   // (x1, y1) to the end point(x1+width1, y1+height1)
   vectPS.setStartPosition(x1, y1);
   vectPS.setDrawingDimensions(width1, height1);
   vectPS.setBorder(2.0);
   vectPS.apply(root1);

   vectPS.setStartPosition(x2, y2);
   vectPS.setDrawingDimensions(width2, height2);
   vectPS.apply(root2);

   ...

   vectPS.setStartPosition(xi, yi);
   vectPS.setDrawingDimensions(widthi, heighti);
   vectPS.apply(rooti);

   vectPS.endPage();
virtual void SoVectorizeAction::enableLighting ( SbBool  flag  )  [inline, virtual]

Allows the user to enable/disable the taking into account of lights in the scene graph during the computation of the vectorized file.

If ...

  • flag = FALSE, whatever the light model, the color of an object is its diffuse color.
  • flag = TRUE and the light model is PHONG, the color of an object depends on its orientation, its material (ambient, diffuse, ..., specular color) and the lights illuminating the object.
virtual void SoVectorizeAction::endPage (  )  [virtual]

Ends a page.

Allows the user to generate multiple plots per page.

virtual SbBool SoVectorizeAction::getBackgroundColor ( SbColor color  )  const [virtual]

Returns the color of the background.

virtual void SoVectorizeAction::getBorder ( float *  w,
SbColor color 
) const [virtual]

Returns the color and the width of the border of the clipping limits.

If width = 0, there is no border.

static SoType SoVectorizeAction::getClassTypeId (  )  [static]

Returns the type identifier for this class.

Reimplemented from SoAction.

Reimplemented in SoVectorizeCGMAction, SoVectorizeGDIAction, SoVectorizeHPGLAction, and SoVectorizePSAction.

virtual SbBool SoVectorizeAction::getColorPriority ( void   )  const [virtual]

Returns the color priority.

virtual ColorTranslationMethod SoVectorizeAction::getColorTranslationMethod (  )  const [virtual]

Returns the method for choosing the color of the drawing on the sheet of paper.

virtual SbVec2f SoVectorizeAction::getDrawingDimensions ( DimensionUnit  u = MM  )  const [virtual]

Returns the dimensions of the drawing on the sheet of paper.

HLHSRMode SoVectorizeAction::getHLHSRMode (  )  const [inline]

Returns the Hidden Line and Hidden Surface Removal mode.

SbBool SoVectorizeAction::getHLHSRRasterCaching (  )  const [inline]

Returns the raster caching flag.

See setHLHSRRasterCaching().

float SoVectorizeAction::getHLHSRRasterQuality (  )  const [inline]

Returns the raster image quality value.

See setHLHSRRasterQuality().

virtual EndLineStyle SoVectorizeAction::getLineEndStyle (  )  const [virtual]

Returns the style for line ends.

virtual JoinLineStyle SoVectorizeAction::getLineJoinsStyle (  )  const [virtual]

Returns the style for line joins.

float SoVectorizeAction::getLineOffset (  )  const [inline]

Returns line offset.

See setPolygonOffset.

virtual float SoVectorizeAction::getLinePatternSize ( DimensionUnit  u = MM  )  const [virtual]

Returns the line pattern scale factor.

float SoVectorizeAction::getMarkerOffset (  )  const [inline]

Returns marker offset.

See setPolygonOffset.

virtual float SoVectorizeAction::getMiterLimit (  )  const [virtual]

Returns the miter limit.

virtual float SoVectorizeAction::getNominalWidth ( DimensionUnit  u = MM  )  const [virtual]

Returns the nominal width.

virtual Orientation SoVectorizeAction::getOrientation (  )  const [virtual]

Returns the orientation of the drawing on the sheet of paper.

virtual void SoVectorizeAction::getPenDescription ( SbColor colors,
float *  widths,
DimensionUnit  u = MM 
) const [virtual]

Returns the description of the color and the width of each pen.

virtual int SoVectorizeAction::getPenNum (  )  const [virtual]

Returns the number of pens.

virtual float SoVectorizeAction::getPixelImageSize ( DimensionUnit  u = MM  )  const [virtual]

Returns the size of a pixel.

float SoVectorizeAction::getPolygonOffset (  )  const [inline]

Returns polygon offset.

See setPolygonOffset.

ShadeModel SoVectorizeAction::getShadeModel (  )  [inline]

Returns the shade model.

virtual SbVec2f SoVectorizeAction::getStartPosition ( DimensionUnit  u = MM  )  const [virtual]

Returns the start position of the drawing on the sheet of paper.

virtual SoType SoVectorizeAction::getTypeId (  )  const [virtual]

Returns the type identifier for this specific instance.

Implements SoTypedObject.

Reimplemented in SoVectorizeCGMAction, SoVectorizeGDIAction, SoVectorizeHPGLAction, and SoVectorizePSAction.

virtual SoVectorOutput* SoVectorizeAction::getVectorOutput (  )  const [virtual]

Output access method.

Returns the SoOutput instance in action.

SbBool SoVectorizeAction::isLightingEnabled (  )  const [inline]

Returns TRUE if lighting is enabled.

virtual void SoVectorizeAction::setBackgroundColor ( SbBool  bg,
SbColor  color 
) [virtual]

Sets the color of the background.

If bg = FALSE, there is no background.

virtual void SoVectorizeAction::setBackgroundColor ( SbBool  bg  )  [inline, virtual]

Enables or disables the background and sets its color to white.

If bg = FALSE, there is no background.

virtual void SoVectorizeAction::setBorder ( float  width,
SbColor  color 
) [virtual]

Sets the color and the width of the border of the clipping limits.

If width = 0, there is no border.

virtual void SoVectorizeAction::setBorder ( float  width  )  [inline, virtual]

Sets the width of the border of the clipping limits.

The color of the border is set to white. If width = 0, there is no border.

virtual void SoVectorizeAction::setColorPriority ( SbBool  priority  )  [virtual]

Sets the color priority flag.

If priority = TRUE, a pen will be chosen according to its color. Otherwise, it will be chosen according to its width.

virtual void SoVectorizeAction::setColorTranslationMethod ( ColorTranslationMethod  method  )  [virtual]

Sets the method for choosing the color of the drawing on the sheet of paper.

The default value is REVERSE_ONLY_BLACK_AND_WHITE. This method is applied for all colors.

virtual void SoVectorizeAction::setDrawingDimensions ( const SbVec2f d,
DimensionUnit  u = MM 
) [virtual]

Sets the dimensions of the drawing on the sheet of paper.

virtual void SoVectorizeAction::setDrawingDimensions ( float  w,
float  h,
DimensionUnit  u = MM 
) [virtual]

Sets the dimensions of the drawing on the sheet of paper.

virtual void SoVectorizeAction::setHLHSRMode ( HLHSRMode  mode  )  [inline, virtual]

Sets the Hidden Line and Hidden Surface Removal mode.

Possible values of mode:

  • NO_HLHSR. Hidden lines and hidden surfaces are not removed.
  • HLHSR_SIMPLE_PAINTER. Simple painter's algorithm is used for HLHSR. Lines and surfaces are sorted by their maximum Z depth and displayed in order from front to back so lines and surfaces that are in the foreground are drawn last. If the scene contains interpenetrating primitives, there may be visibility errors in the resulting output.
  • HLHSR_PAINTER. Like the simple painter's algorithm, the primitives are depth sorted and displayed from front to back. In addition, some ambiguities where the polygons' Z extents overlap are resolved. Primitives that intersect other primitives are split and the new pieces sorted to provide more correct visual results. This mode is slower than the HLHSR_SIMPLE_PAINTER mode.
  • HLHSR_PAINTER_SURFACE_REMOVAL. This mode is the same as the previous, but a first pass removes surfaces that are completely hidden. The method used to remove hidden surfaces is a pixel rendering method, so for very small surfaces, some accuracy errors can occur. Because some surfaces are removed before the painter's algorithm is applied, this method can be significantly faster than the previous one. Generally output files are smaller than using the previous method.
  • HLHSR_RASTER. A raster image is generated and vectorized to determine visible primitives.
  • HIDDEN_LINES_REMOVAL. This mode removes all hidden lines. Whether the screen render style is FILLED or LINES, the output render style will be lines. This mode is very slow but gives correct results.
void SoVectorizeAction::setHLHSRRasterCaching ( SbBool  enable  )  [inline]

Enables/disables the use of OpenGL display lists to generate the raster image with the HLHSR_RASTER algorithm.

Enabled by default.

void SoVectorizeAction::setHLHSRRasterQuality ( float  quality  )  [inline]

Sets the quality of the raster image generated to vectorize visible primitives with the HLHSR_RASTER algorithm.

0 is the worst quality, 1 is the best.

virtual void SoVectorizeAction::setLineEndStyle ( EndLineStyle  style  )  [virtual]

Sets the style for line ends.

virtual void SoVectorizeAction::setLineJoinsStyle ( JoinLineStyle  style  )  [virtual]

Sets the style for line joins.

void SoVectorizeAction::setLineOffset ( float  offset  )  [inline]

Sets line offset.

See setPolygonOffset.

virtual void SoVectorizeAction::setLinePatternSize ( float  w,
DimensionUnit  u = MM 
) [virtual]

Sets the line pattern size, i.e., the association between printer pattern (16 printer "points") and the size of the line pattern on the hard copy output.

One printer pattern is equal to SoDrawStyleElement::linePatternScaleFactor * w units where units are millimeters, meters, inches. By default one printer pattern equals 5.6444 millimeters (16 * .3527 mm/point). Used for the following attributes: line pattern length.

void SoVectorizeAction::setMarkerOffset ( float  offset  )  [inline]

Sets marker offset.

See setPolygonOffset.

virtual void SoVectorizeAction::setMiterLimit ( float  limit  )  [virtual]

Sets the miter limit.

virtual void SoVectorizeAction::setNominalWidth ( float  w,
DimensionUnit  u = MM 
) [virtual]

Sets the nominal width.

For sizes specified in "points" (equals 1/72 inch), specifies the physical size of the "point" on the hard copy output. One printer point is equal to w units where units are millimeters, meters, inches. By default 1 printer point equals approximately 0.3527 millimeters. Used for the following attributes: line width, point size, text size, and text space.

virtual void SoVectorizeAction::setOrientation ( Orientation  o  )  [virtual]

Sets the orientation of the drawing on the sheet of paper.

virtual void SoVectorizeAction::setPenDescription ( int  num_pens,
const SbColor colors = 0,
const float *  widths = 0,
DimensionUnit  u = MM 
) [virtual]

Sets the description of the color and the width of each pen.

The function is useful for pen plotters, but can also be used for raster plotters. For raster plotters, the drawing color is the color of the chosen pen. This is useful to force the plotter to use a set of colors. If the width parameter is not specified, a 0.35 mm value is assumed.

virtual void SoVectorizeAction::setPixelImageSize ( float  w,
DimensionUnit  u = MM 
) [virtual]

Sets the size of a pixel for image primitives.

For sizes specified in pixels, specifies the physical size of a "pixel" on the hard copy output. One pixel is equal to w units where units are millimeters, meters, inches. By default 1 pixel equals 0.35 millimeters. Used for the following attributes: images.

void SoVectorizeAction::setPolygonOffset ( float  offset  )  [inline]

Method to set the Z offset to be applied to polygons in normalized device coordinates (-1 to 1 space).

This is useful for separating coplanar lines and polygons. Similar to SoPolygonOffset, a positive offset value moves the primitives away from the camera and a negative value pulls them closer. There are separate methods for lines (setLineOffset) and markers (setMarkerOffset). The default value for the offset methods is zero.

Generally applications should avoid using lines and polygons that are exactly coplanar. Correct results cannot be guaranteed for normal or vectorized rendering. SoPolygonOffset can significantly reduce the problem for normal rendering, but has no effect on vectorized rendering. However a Z offset of approximately 0.01 applied to polygons will usually improve the appearance of vectorized coplanar primitives. Applying too large an offset may cause the converse visual artifact where lines that should be hidden become visible.

void SoVectorizeAction::setShadeModel ( ShadeModel  model  )  [inline]

Selects FLAT or SMOOTH shading.

virtual void SoVectorizeAction::setStartPosition ( const SbVec2f p,
DimensionUnit  u = MM 
) [virtual]

Sets the start position of the drawing on the sheet of paper.

virtual void SoVectorizeAction::setStartPosition ( float  x,
float  y,
DimensionUnit  u = MM 
) [virtual]

Sets the start position of the drawing on the sheet of paper.


Friends And Related Function Documentation

friend class SoHLHSRImageVectorizer [friend]
friend class SoHLHSRVectorize [friend]

The documentation for this class was generated from the following file:

Open Inventor Toolkit reference manual, generated on 15 Mar 2023
Copyright © Thermo Fisher Scientific All rights reserved.
http://www.openinventor.com/