VS:OffsetPoly: Difference between revisions

From Vectorworks Developer
Jump to navigation Jump to search
m (1 revision)
 
(add remark: this is still unusable, correct introduction: public since 2012)
(2 intermediate revisions by the same user not shown)
Line 5: Line 5:
-----------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------
<desc>
<desc>
Returns a poly, or the handle to a group of polys, which is the result of offsetting the input handle.
Offsets a polygon or polyline. Must handle open &amp; closed polys. A positive distance offsets to the outside; negative to the inside. Should remove self-intersecting segments from the result. Should support &quot;smooth&quot; vs. &quot;sharp&quot; offsets.</desc>
 
The input handle can be a:
*line
*arc or circle
*rectangle
*rounded rectangle
*ellipse
*polygon (open or closed)
*polyline (open or closed)
*group containing one or more of these objects
 
When offsetting a line, a positive offsetDistance will offset to the left, looking from the start to the end of the line.
 
When offsetting an arc, a positive offsetDistance will create a polyline approximation of an arc of a larger radius.
 
When offsetting any closed shape, a positive offsetDistance will offset to the outside.
 
When offsetting an open polygon or polyline, the direction of the offset will depend on the overall sense of the poly. From start to end, if the poly turns right more than left, the offset will be to the left, if offsetDistance is positive.
 
Removes self-intersecting segments from the result, making it useful for offsetting when interference is an issue.
 
Returns the handle to the newly created polyline, or to a group if the result contains more than one polyline. The return will be a group if numberOfOffsets is greater than 1, or if offsetDistance is negative, and the removal of self-intersecting segments resulted in multiple objects.
 
If consolidateVertices is TRUE, nearly colinear straight segments will be consolidated into a single straight segment, and nearly concentric arc segments will be consolidated into a single arc (approximated by polygon vertices).  
 
If sharpCorners is FALSE, when offsetting a convex intersection, an arc will be created, centered at the intersection, to transition from one segment to the next. If it is TRUE, no arc will be inserted, and the adjacent offset segments will be extended to their intersection. If no intersection exists, such as when offsetting a line, and the adjacent offset segments are parallel, arcs will be introduced to transition between the segments.
 
ConversionRes is the "2D Conversion Resolution" that will be used to polygonalize the polyline prior to offsetting. It should be possible to set this to a pretty low number if you're also using consolidateVertices, since this will replace line segments with arcs where possible.
 
ConsolidationTolerance is total allowable chordal variance between line segments and the arc, if consolidateVertices is TRUE.
</desc>


-----------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------
<def>
<def>
<funcDef lang="vs">
<funcDef lang="vs">
FUNCTION OffsetPoly(h :HANDLE; offsetDistance :REAL; numberOfOffsets :INTEGER; consolidateVertices :BOOLEAN; sharpCorners :BOOLEAN; conversionRes :INTEGER; consolidationTolerance :REAL) :HANDLE;
FUNCTION OffsetPoly(h:HANDLE; offsetDistance:REAL; numberOfOffsets:INTEGER; consolidateVertices:BOOLEAN; sharpCorners:BOOLEAN; conversionRes:INTEGER; consolidationTolerance:REAL) : HANDLE;
</funcDef>
</funcDef>
<funcDef lang="py">
<funcDef lang="py">
Line 89: Line 58:
</lineList>
</lineList>
</params>
</params>
-----------------------------------------------------------------------------------------------------------
<return>
</return>


-----------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------
<remark>
<remark>
[[User:Orso.b.schmid| Orso]] (2010/03/19) This fails at least on metric units whenever the offset is less than 1. It makes a copy in place instead. For example:
([[User:Orso.b.schmid|Orso]], 2011): The routine was introduced undocumented by VW10 (2005), then made public by VW17 (2012).
* Units meter, offset 1m > succeeds
* Units meter, offset 0.9m > fails
 
* Units centimeter, offset 1cm > succeeds
* Units centimeter, offset 0.9cm > fails


Thank you Petri for pointing this out to me. :)
OffsetPoly fails:
* on holes, they are ignored
* when by an offset less than 1 unit: it copies in place, instead of offsetting (tested from VW 2011 through 2014). For example:
:* Units meter, offset 1m > succeeds
:* Units meter, offset 0.9m > fails
:* Units cm, offset 1cm > succeeds
:* Units cm, offset 0.9cm > fails
</remark>
</remark>


-----------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------
<sample>
<sample></sample>
<code lang="pas">
PROCEDURE Example;
  {Offsets the selected object.}
VAR
  h :HANDLE;
  dist :REAL;
  numberOfOffsets :INTEGER;
  consolidateVertices :BOOLEAN;
  sharpCorners :BOOLEAN;
  conversionRes: INTEGER;
  consolidationTolerance: REAL;
BEGIN
  dist := 100;
  numberOfOffsets := 1;
  consolidateVertices := false;
  sharpCorners := false;
  conversionRes := 16;
  consolidationTolerance := 1;
  h := OffsetPoly(FSActLayer, dist, numberOfOffsets, consolidateVertices, sharpCorners, conversionRes, consolidationTolerance);
END;
RUN(Example);</code>


</sample>
-----------------------------------------------------------------------------------------------------------
<seeAlso>
Similar calls:
* [[VS:OffsetPolyN]]
* [[VS:OffsetHandle]]
</seeAlso>


-----------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------
<version>
<version>
Availability: from All Versions
Availability: from Vectorworks 2012


This is drop-in function.
</version>
</version>
-----------------------------------------------------------------------------------------------------------
<seeAlso>
[[VS:OffsetPolyN| OffsetPolyN]]
[[VS:OffsetHandle| OffsetHandle]]
</seeAlso>


</vwDoc>
</vwDoc>


[[Category:VS Function Reference|OffsetPoly]]
[[Category:VS Function Reference|OffsetPoly]]
[[Category:VS Function Reference:Objects - Polys|OffsetPoly]]
[[Category:VS Function Reference:Graphic Calculation|OffsetPoly]]

Revision as of 08:43, 25 March 2014

.VectorScript|VectorScript ..VS:Function Reference|Function Reference ..VS:Function_Reference_Appendix|Appendix

Description

Offsets a polygon or polyline. Must handle open & closed polys. A positive distance offsets to the outside; negative to the inside. Should remove self-intersecting segments from the result. Should support "smooth" vs. "sharp" offsets.

FUNCTION OffsetPoly(
h :HANDLE;
offsetDistance :REAL;
numberOfOffsets :INTEGER;
consolidateVertices :BOOLEAN;
sharpCorners :BOOLEAN;
conversionRes :INTEGER;
consolidationTolerance :REAL) : HANDLE;
def vs.OffsetPoly(h, offsetDistance, numberOfOffsets, consolidateVertices, sharpCorners, conversionRes, consolidationTolerance):
    return HANDLE

Parameters

h HANDLE
offsetDistance REAL
numberOfOffsets INTEGER
consolidateVertices BOOLEAN
sharpCorners BOOLEAN
conversionRes INTEGER
consolidationTolerance REAL

Remarks

(Orso, 2011): The routine was introduced undocumented by VW10 (2005), then made public by VW17 (2012).

OffsetPoly fails:

  • on holes, they are ignored
  • when by an offset less than 1 unit: it copies in place, instead of offsetting (tested from VW 2011 through 2014). For example:
  • Units meter, offset 1m > succeeds
  • Units meter, offset 0.9m > fails
  • Units cm, offset 1cm > succeeds
  • Units cm, offset 0.9cm > fails

Version

Availability: from Vectorworks 2012

See Also

Similar calls:

Similar calls:
  • [[VS:OffsetPolyN]]
  • [[VS:OffsetHandle]]