1.. _tut_linear_dimension: 2 3Tutorial for Linear Dimensions 4============================== 5 6The :class:`~ezdxf.entities.Dimension` entity is the generic entity for all dimension types, but unfortunately 7AutoCAD is **not willing** to show a dimension line defined only by this dimension entity, it also needs an 8anonymous block which contains the dimension line shape constructed by basic DXF entities like LINE and TEXT 9entities, this representation is called the dimension line `rendering` in this documentation, beside the fact 10this is not a real graphical rendering. BricsCAD is a much more friendly CAD application, which do show the 11dimension entity without the graphical rendering as block, which was very useful for testing, because there is no 12documentation how to apply all the dimension style variables (more than 80). 13This seems to be the reason why dimension lines are rendered so differently by many CAD application. 14 15Don't expect to get the same rendering results by `ezdxf` as you get from AutoCAD, `ezdxf` tries 16to be as close to the results rendered by BricsCAD, but it was not possible to implement all 17the various combinations of dimension style parameters. 18 19Text rendering is another problem, because `ezdxf` has no real rendering engine. Some font properties, like the real 20text width, are not available to `ezdxf` and may also vary slightly for different CAD applications. 21The text properties in `ezdxf` are based on the default monospaced standard font, but for TrueType fonts the space 22around the text is much bigger than needed. 23 24Not all DIMENSION and DIMSTYLE features are supported by all DXF versions, especially DXF R12 does not support many 25features, but in this case the required rendering of dimension lines is an advantage, because if the application 26just shows the rendered block, all features which can be used in DXF R12 are displayed like linetypes, but they 27disappear if the dimension line is edited in the application. `ezdxf` writes only the supported DIMVARS of the 28used DXF version to avoid invalid DXF files. So it is not that critical to know all the supported features of a 29DXF version, except for limits and tolerances, `ezdxf` uses the advanced features of MTEXT to create limits 30and tolerances and therefore they are not supported (displayed) in DXF R12 files. 31 32.. seealso:: 33 34 - Graphical reference of many DIMVARS and some advanced information: :ref:`dimstyle_table_internals` 35 - Source code file `standards.py`_ shows how to create your own DIMSTYLES. 36 - `dimension_linear.py`_ for linear dimension examples. 37 38Horizontal Dimension 39-------------------- 40 41.. code-block:: Python 42 43 import ezdxf 44 45 # Argument setup=True setups the default dimension styles 46 doc = ezdxf.new('R2010', setup=True) 47 48 # Add new dimension entities to the modelspace 49 msp = doc.modelspace() 50 # Add a LINE entity, not required 51 msp.add_line((0, 0), (3, 0)) 52 # Add a horizontal dimension, default dimension style is 'EZDXF' 53 dim = msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0)) 54 # Necessary second step, to create the BLOCK entity with the dimension geometry. 55 # Additional processing of the dimension line could happen between adding and 56 # rendering call. 57 dim.render() 58 doc.saveas('dim_linear_horiz.dxf') 59 60.. image:: gfx/dim_linear_horiz.png 61 62 63The example above creates a horizontal :class:`~ezdxf.entities.Dimension` entity, the default dimension style 64``'EZDXF'`` and is defined as 1 drawing unit is 1m in reality, the drawing scale 1:100 and the length factor is 100, 65which creates a measurement text in cm. 66 67The `base` point defines the location of the dimension line, `ezdxf` accepts any point on the dimension line, 68the point `p1` defines the start point of the first extension line, which also defines the first measurement point 69and the point `p2` defines the start point of the second extension line, which also defines the second 70measurement point. 71 72The return value `dim` is **not** a dimension entity, instead a :class:`~ezdxf.entities.DimStyleOverride` object is 73returned, the dimension entity is stored as `dim.dimension`. 74 75Vertical and Rotated Dimension 76------------------------------ 77 78Argument `angle` defines the angle of the dimension line in relation to the x-axis of the WCS or UCS, measurement 79is the distance between first and second measurement point in direction of `angle`. 80 81.. code-block:: Python 82 83 # assignment to dim is not necessary, if no additional processing happens 84 msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0), angle=-30).render() 85 doc.saveas('dim_linear_rotated.dxf') 86 87.. image:: gfx/dim_linear_rotated.png 88 89For a vertical dimension set argument `angle` to 90 degree, but in this example the vertical distance would be 0. 90 91Aligned Dimension 92----------------- 93 94An aligned dimension line is parallel to the line defined by the definition points `p1` and `p2`. The placement of the 95dimension line is defined by the argument `distance`, which is the distance between the definition line and the 96dimension line. The `distance` of the dimension line is orthogonal to the base line in counter clockwise orientation. 97 98.. code-block:: Python 99 100 msp.add_line((0, 2), (3, 0)) 101 dim = msp.add_aligned_dim(p1=(0, 2), p2=(3, 0), distance=1) 102 doc.saveas('dim_linear_aligned.dxf') 103 104.. image:: gfx/dim_linear_aligned.png 105 106Dimension Style Override 107------------------------ 108 109Many dimension styling options are defined by the associated :class:`~ezdxf.entities.DimStyle` entity. 110But often you wanna change just a few settings without creating a new dimension style, therefore the 111DXF format has a protocol to store this changed settings in the dimension entity itself. 112This protocol is supported by `ezdxf` and every factory function which creates dimension 113entities supports the `override` argument. 114This `override` argument is a simple Python dictionary 115(e.g. :code:`override = {'dimtad': 4}`, place measurement text below dimension line). 116 117The overriding protocol is managed by the :class:`~ezdxf.entities.DimStyleOverride` object, 118which is returned by the most dimension factory functions. 119 120Placing Measurement Text 121------------------------ 122 123The "default" location of the measurement text depends on various :class:`~ezdxf.entities.DimStyle` parameters and is 124applied if no user defined text location is defined. 125 126Default Text Locations 127~~~~~~~~~~~~~~~~~~~~~~ 128 129"Horizontal direction" means in direction of the dimension line and "vertical direction" means perpendicular to the 130dimension line direction. 131 132The **"horizontal"** location of the measurement text is defined by :attr:`~ezdxf.entities.DimStyle.dxf.dimjust`: 133 134=== ===== 1350 Center of dimension line 1361 Left side of the dimension line, near first extension line 1372 Right side of the dimension line, near second extension line 1383 Over first extension line 1394 Over second extension line 140=== ===== 141 142.. code-block:: Python 143 144 msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0), override={'dimjust': 1}).render() 145 146.. image:: gfx/dim_linear_dimjust.png 147 148The **"vertical"** location of the measurement text relative to the dimension line is defined by 149:attr:`~ezdxf.entities.DimStyle.dxf.dimtad`: 150 151=== ===== 1520 Center, it is possible to adjust the vertical location by :attr:`~ezdxf.entities.DimStyle.dxf.dimtvp` 1531 Above 1542 Outside, handled like `Above` by `ezdxf` 1553 JIS, handled like `Above` by `ezdxf` 1564 Below 157=== ===== 158 159.. code-block:: Python 160 161 msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0), override={'dimtad': 4}).render() 162 163.. image:: gfx/dim_linear_dimtad.png 164 165The distance between text and dimension line is defined by :attr:`~ezdxf.entities.DimStyle.dxf.dimgap`. 166 167The :class:`~ezdxf.entities.DimStyleOverride` object has a method :meth:`~ezdxf.entities.DimStyleOverride.set_text_align` 168to set the default text location in an easy way, this is also the reason for the 2 step creation process of 169dimension entities: 170 171.. code-block:: Python 172 173 dim = msp.add_linear_dim(base=(3, 2), p1=(0, 0), p2=(3, 0)) 174 dim.set_text_align(halign='left', valign='center') 175 dim.render() 176 177====== ===== 178halign ``'left'``, ``'right'``, ``'center'``, ``'above1'``, ``'above2'`` 179valign ``'above'``, ``'center'``, ``'below'`` 180====== ===== 181 182Run function :func:`example_for_all_text_placings_R2007` in the example script `dimension_linear.py`_ 183to create a DXF file with all text placings supported by `ezdxf`. 184 185 186User Defined Text Locations 187~~~~~~~~~~~~~~~~~~~~~~~~~~~ 188 189Beside the default location, it is possible to locate the measurement text freely. 190 191Location Relative to Origin 192+++++++++++++++++++++++++++ 193 194The user defined text location can be set by the argument `location` in most dimension factory functions and 195always references the midpoint of the measurement text: 196 197.. code-block:: Python 198 199 msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0), location=(4, 4)).render() 200 201.. image:: gfx/dim_linear_user_location_absolute.png 202 203The `location` is relative to origin of the active coordinate system or WCS if no UCS is defined in the 204:meth:`~ezdxf.entities.DimStyleOverride.render` method, the user defined `location` can also be set by 205:meth:`~ezdxf.entities.DimStyleOverride.user_location_override`. 206 207Location Relative to Center of Dimension Line 208+++++++++++++++++++++++++++++++++++++++++++++ 209 210The method :meth:`~ezdxf.entities.DimStyleOverride.set_location` has additional features for linear dimensions. 211Argument `leader` = ``True`` adds a simple leader from the measurement text to the center of the dimension line and 212argument `relative` = ``True`` places the measurement text relative to the center of the dimension line. 213 214.. code-block:: Python 215 216 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 217 dim.set_location(location=(-1, 1), leader=True, relative=True) 218 dim.render() 219 220.. image:: gfx/dim_linear_user_location_relative.png 221 222Location Relative to Default Location 223+++++++++++++++++++++++++++++++++++++ 224 225The method :meth:`~ezdxf.entities.DimStyleOverride.shift_text` shifts the measurement text away from the default text 226location. Shifting directions are aligned to the text direction, which is the direction of the dimension line in most 227cases, `dh` (for delta horizontal) shifts the text parallel to the text direction, `dv` (for delta vertical) shifts the 228text perpendicular to the text direction. This method does not support leaders. 229 230.. code-block:: Python 231 232 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 233 dim.shift_text(dh=1, dv=1) 234 dim.render() 235 236.. image:: gfx/dim_linear_user_location_shift.png 237 238.. _tut_measurement_text_formatting_and_styling: 239 240Measurement Text Formatting and Styling 241--------------------------------------- 242 243Text Properties 244~~~~~~~~~~~~~~~ 245 246=================== =========================================== 247DIMVAR Description 248=================== =========================================== 249:attr:`dimtxsty` Specifies the text style of the dimension as :class:`~ezdxf.entities.Textstyle` name. 250:attr:`dimtxt` Text height in drawing units. 251:attr:`dimclrt` Measurement text color as :ref:`ACI`. 252=================== =========================================== 253 254.. code-block:: Python 255 256 msp.add_linear_dim( 257 base=(3, 2), p1=(3, 0), p2=(6, 0), 258 override={ 259 'dimtxsty': 'Standard', 260 'dimtxt': 0.35, 261 'dimclrt': 1, 262 }).render() 263 264.. image:: gfx/dim_linear_text.png 265 266 267Background Filling 268~~~~~~~~~~~~~~~~~~ 269 270Background fillings are supported since DXF R2007, and `ezdxf` uses the MTEXT entity to implement this 271feature, so setting background filling in DXF R12 has no effect. 272 273Set :attr:`~ezdxf.entities.DimStyle.dxf.dimtfill` to ``1`` to use the canvas color as background filling or set 274:attr:`~ezdxf.entities.DimStyle.dxf.dimtfill` to ``2`` to use :attr:`~ezdxf.entities.DimStyle.dxf.dimtfillclr` as 275background filling, color value as :ref:`ACI`. Set :attr:`~ezdxf.entities.DimStyle.dxf.dimtfill` to ``0`` to 276disable background filling. 277 278=================== ============================================================================== 279DIMVAR Description 280=================== ============================================================================== 281:attr:`dimtfill` Enables background filling if bigger than ``0`` 282:attr:`dimtfillclr` Fill color as :ref:`ACI`, if :attr:`dimtfill` is ``2`` 283=================== ============================================================================== 284 285=================== ==================================================== 286:attr:`dimtfill` Description 287=================== ==================================================== 288``0`` disabled 289``1`` canvas color 290``2`` color defined by :attr:`dimtfillclr` 291=================== ==================================================== 292 293.. code-block:: Python 294 295 msp.add_linear_dim( 296 base=(3, 2), p1=(3, 0), p2=(6, 0), 297 override={ 298 'dimtfill': 2, 299 'dimtfillclr': 1, 300 }).render() 301 302.. image:: gfx/dim_linear_bg_filling.png 303 304Text Formatting 305~~~~~~~~~~~~~~~ 306 307- Set decimal places: :attr:`~ezdxf.entities.DimStyle.dxf.dimdec` defines the number of decimal places displayed for the 308 primary units of a dimension. (DXF R2000) 309- Set decimal point character: :attr:`~ezdxf.entities.DimStyle.dxf.dimdsep` defines the decimal point as ASCII code, 310 use :code:`ord('.')` 311- Set rounding: :attr:`~ezdxf.entities.DimStyle.dxf.dimrnd`, rounds all dimensioning distances to the specified 312 value, for instance, if :attr:`dimrnd` is set to ``0.25``, all distances round to the nearest 0.25 unit. 313 If :attr:`dimrnd` is set to ``1.0``, all distances round to the nearest integer. For more information look at 314 the documentation of the :func:`ezdxf.math.xround` function. 315- Set zero trimming: :attr:`~ezdxf.entities.DimStyle.dxf.dimzin`, `ezdxf` supports only: ``4`` suppress leading zeros 316 and ``8``: suppress trailing zeros and both as ``12``. 317- Set measurement factor: scale measurement by factor :attr:`~ezdxf.entities.DimStyle.dxf.dimlfac`, e.g. to get the 318 dimensioning text in cm for a DXF file where 1 drawing unit represents 1m, set :attr:`dimlfac` to ``100``. 319- Text template for measurement text is defined by :attr:`~ezdxf.entities.DimStyle.dxf.dimpost`, ``'<>'`` represents the 320 measurement text, e.g. ``'~<>cm'`` produces ``'~300cm'`` for measurement in previous example. 321 322To set this values the :meth:`ezdxf.entities.DimStyle.set_text_format` and 323:meth:`ezdxf.entities.DimStyleOverride.set_text_format` methods are very recommended. 324 325.. _tut_overriding_measurement_text: 326 327Overriding Measurement Text 328--------------------------- 329 330Measurement text overriding is stored in the :class:`~ezdxf.entities.Dimension` entity, the content of 331to DXF attribute :class:`~ezdxf.entities.Dimension.dxf.text` represents the override value as string. 332Special values are one space ``' '`` to just suppress the measurement text, an empty string ``''`` or ``'<>'`` 333to get the regular measurement. 334 335All factory functions have an explicit `text` argument, which always replaces the `text` value in the 336`dxfattribs` dict. 337 338.. code-block:: Python 339 340 msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0), text='>1m').render() 341 342.. image:: gfx/dim_linear_text_override.png 343 344.. _tut_dimension_line_properties: 345 346Dimension Line Properties 347------------------------- 348 349The dimension line color is defined by the DIMVAR :attr:`dimclrd` as :ref:`ACI`, 350:attr:`dimclrd` also defines the color of the arrows. The linetype is defined by :attr:`dimltype` 351but requires DXF R2007 for full support by CAD Applications and the line weight is defined by 352:attr:`dimlwd` (DXF R2000), see also the :attr:`~ezdxf.entities.DXFGraphic.dxf.lineweight` reference 353for valid values. The :attr:`dimdle` is the extension of the dimension line beyond the extension 354lines, this dimension line extension is not supported for all arrows. 355 356=================== ============================================================================== 357DIMVAR Description 358=================== ============================================================================== 359:attr:`dimclrd` dimension line and arrows color as :ref:`ACI` 360:attr:`dimltype` linetype of dimension line 361:attr:`dimlwd` line weight of dimension line 362:attr:`dimdle` extension of dimension line in drawing units 363=================== ============================================================================== 364 365.. code-block:: Python 366 367 msp.add_linear_dim( 368 base=(3, 2), p1=(3, 0), p2=(6, 0), 369 override={ 370 'dimclrd': 1, # red 371 'dimdle': 0.25, 372 'dimltype': 'DASHED2', 373 'dimlwd': 35, # 0.35mm line weight 374 }).render() 375 376.. image:: gfx/dim_linear_dimline_properties.png 377 378:meth:`~ezdxf.entities.DimStyleOverride` method: 379 380.. code-block:: Python 381 382 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 383 dim.set_dimline_format(color=1, linetype='DASHED2', lineweight=35, extension=0.25) 384 dim.render() 385 386.. _tut_extension_line_properties: 387 388Extension Line Properties 389------------------------- 390 391The extension line color is defined by the DIMVAR :attr:`dimclre` as :ref:`ACI`. 392The linetype for first and second extension line is defined by :attr:`dimltex1` and :attr:`dimltex2` but requires DXF 393R2007 for full support by CAD Applications and the line weight is defined by :attr:`dimlwe` (DXF R2000), see also the 394:attr:`~ezdxf.entities.DXFGraphic.dxf.lineweight` reference for valid values. 395 396The :attr:`dimexe` is the extension of the extension line beyond the dimension line, and :attr:`dimexo` defines the 397offset of the extension line from the measurement point. 398 399=================== ================================================================================================ 400DIMVAR Description 401=================== ================================================================================================ 402:attr:`dimclre` extension line color as :ref:`ACI` 403:attr:`dimltex1` linetype of first extension line 404:attr:`dimltex2` linetype of second extension line 405:attr:`dimlwe` line weight of extension line 406:attr:`dimexe` extension beyond dimension line in drawing units 407:attr:`dimexo` offset of extension line from measurement point 408:attr:`dimfxlon` set to ``1`` to enable fixed length extension line 409:attr:`dimfxl` length of fixed length extension line in drawing units 410:attr:`dimse1` suppress first extension line if ``1`` 411:attr:`dimse2` suppress second extension line if ``1`` 412=================== ================================================================================================ 413 414.. code-block:: Python 415 416 msp.add_linear_dim( 417 base=(3, 2), p1=(3, 0), p2=(6, 0), 418 override={ 419 'dimclre': 1, # red 420 'dimltex1': 'DASHED2', 421 'dimltex2': 'CENTER2', 422 'dimlwe': 35, # 0.35mm line weight 423 'dimexe': 0.3, # length above dimension line 424 'dimexo': 0.1, # offset from measurement point 425 }).render() 426 427.. image:: gfx/dim_linear_extline_properties.png 428 429:meth:`~ezdxf.entities.DimStyleOverride` methods: 430 431.. code-block:: Python 432 433 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 434 dim.set_extline_format(color=1, lineweight=35, extension=0.3, offset=0.1) 435 dim.set_extline1(linetype='DASHED2') 436 dim.set_extline2(linetype='CENTER2') 437 dim.render() 438 439Fixed length extension lines are supported in DXF R2007+, set :attr:`dimfxlon` to ``1`` and :attr:`dimfxl` defines 440the length of the extension line starting at the dimension line. 441 442.. code-block:: Python 443 444 msp.add_linear_dim( 445 base=(3, 2), p1=(3, 0), p2=(6, 0), 446 override={ 447 'dimfxlon': 1, # fixed length extension lines 448 'dimexe': 0.2, # length above dimension line 449 'dimfxl': 0.4, # length below dimension line 450 }).render() 451 452.. image:: gfx/dim_linear_extline_dimfxl.png 453 454:meth:`~ezdxf.entities.DimStyleOverride` method: 455 456.. code-block:: Python 457 458 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 459 dim.set_extline_format(extension=0.2, fixed_length=0.4) 460 dim.render() 461 462To suppress extension lines set :attr:`dimse1` = ``1`` to suppress the first extension 463line and :attr:`dimse2` = ``1`` to suppress the second extension line. 464 465.. code-block:: Python 466 467 msp.add_linear_dim( 468 base=(3, 2), p1=(3, 0), p2=(6, 0), 469 override={ 470 'dimse1': 1, # suppress first extension line 471 'dimse2': 1, # suppress second extension line 472 'dimblk': ezdxf.ARROWS.closed_filled, # arrows just looks better 473 }).render() 474 475.. image:: gfx/dim_linear_extline_suppress.png 476 477:meth:`~ezdxf.entities.DimStyleOverride` methods: 478 479.. code-block:: Python 480 481 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 482 dim.set_arrows(blk=ezdxf.ARROWS.closed_filled) 483 dim.set_extline1(disable=True) 484 dim.set_extline2(disable=True) 485 dim.render() 486 487.. _tut_arrows: 488 489Arrows 490------ 491 492"Arrows" mark then beginning and the end of a dimension line, and most of them do not look like arrows. 493 494DXF distinguish between the simple tick and arrows as blocks. 495 496Using the simple tick by setting tick size :attr:`~ezdxf.entities.DimStyle.dxf.dimtsz` != ``0`` 497also disables arrow blocks as side effect: 498 499.. code-block:: Python 500 501 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 502 dim.set_tick(size=0.25) 503 dim.render() 504 505`ezdxf` uses the ``"ARCHTICK"`` block at double size to render the tick (AutoCAD and BricsCad just 506draw a simple line), so there is no advantage of using the tick instead of an arrow. 507 508Using arrows: 509 510.. code-block:: Python 511 512 dim = msp.add_linear_dim(base=(3, 2), p1=(3, 0), p2=(6, 0)) 513 dim.set_arrow(blk="OPEN_30", size=0.25) 514 dim.render() 515 516 517=================== ==================================================================================== 518DIMVAR Description 519=================== ==================================================================================== 520:attr:`dimtsz` tick size in drawing units, set to ``0`` to use arrows 521:attr:`dimblk` set both arrow block names at once 522:attr:`dimblk1` first arrow block name 523:attr:`dimblk2` second arrow block name 524:attr:`dimasz` arrow size in drawing units 525=================== ==================================================================================== 526 527.. code-block:: Python 528 529 msp.add_linear_dim( 530 base=(3, 2), p1=(3, 0), p2=(6, 0), 531 override={ 532 'dimtsz': 0, # set tick size to 0 to enable arrow usage 533 'dimasz': 0.25, # arrow size in drawing units 534 'dimblk': "OPEN_30", # arrow block name 535 }).render() 536 537Dimension line extension (:attr:`dimdle`) works only for a few arrow blocks and the simple tick: 538 539- ``"ARCHTICK"`` 540- ``"OBLIQUE"`` 541- ``"NONE"`` 542- ``"SMALL"`` 543- ``"DOTSMALL"`` 544- ``"INTEGRAL"`` 545 546Arrow Shapes 547~~~~~~~~~~~~ 548 549.. image:: gfx/all_arrows.png 550 551Arrow Names 552~~~~~~~~~~~ 553 554The arrow names are stored as attributes in the :code:`ezdxf.ARROWS` object. 555 556=========================== ======================== 557closed_filled ``""`` (empty string) 558dot ``"DOT"`` 559dot_small ``"DOTSMALL"`` 560dot_blank ``"DOTBLANK"`` 561origin_indicator ``"ORIGIN"`` 562origin_indicator_2 ``"ORIGIN2"`` 563open ``"OPEN"`` 564right_angle ``"OPEN90"`` 565open_30 ``"OPEN30"`` 566closed ``"CLOSED"`` 567dot_smallblank ``"SMALL"`` 568none ``"NONE"`` 569oblique ``"OBLIQUE"`` 570box_filled ``"BOXFILLED"`` 571box ``"BOXBLANK"`` 572closed_blank ``"CLOSEDBLANK"`` 573datum_triangle_filled ``"DATUMFILLED"`` 574datum_triangle ``"DATUMBLANK"`` 575integral ``"INTEGRAL"`` 576architectural_tick ``"ARCHTICK"`` 577ez_arrow ``"EZ_ARROW"`` 578ez_arrow_blank ``"EZ_ARROW_BLANK"`` 579ez_arrow_filled ``"EZ_ARROW_FILLED"`` 580=========================== ======================== 581 582.. _tut_tolerances_and_limits: 583 584Tolerances and Limits 585--------------------- 586 587The tolerances ans limits features are implemented by using the :class:`~ezdxf.entities.MText` entity, therefore 588DXF R2000+ is required to use these features. It is not possible to use both tolerances and limits at the same time. 589 590Tolerances 591~~~~~~~~~~ 592 593Geometrical tolerances are shown as additional text appended to the measurement text. 594It is recommend to use :meth:`~ezdxf.entities.DimStyleOverride.set_tolerance` method in 595:class:`~ezdxf.entities.DimStyleOverride` or :class:`~ezdxf.entities.DimStyle`. 596 597The attribute :attr:`dimtp` defines the upper tolerance value, :attr:`dimtm` defines the lower tolerance value if 598present, else the lower tolerance value is the same as the upper tolerance value. 599Tolerance values are shown as given! 600 601Same upper and lower tolerance value: 602 603.. code-block:: python 604 605 dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0)) 606 dim.set_tolerance(.1, hfactor=.4, align="top", dec=2) 607 dim.render() 608 609.. image:: gfx/dim_linear_tol.png 610 611Different upper and lower tolerance values: 612 613.. code-block:: python 614 615 dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0)) 616 dim.set_tolerance(upper=.1, lower=.15, hfactor=.4, align="middle", dec=2) 617 dim.render() 618 619.. image:: gfx/dim_linear_tol_upr_lwr.png 620 621The attribute :attr:`dimtfac` specifies a scale factor for the text height of limits and tolerance values 622relative to the dimension text height, as set by :attr:`dimtxt`. For example, if :attr:`dimtfac` is set to 623``1.0``, the text height of fractions and tolerances is the same height as the dimension text. 624If :attr:`dimtxt` is set to ``0.75``, the text height of limits and tolerances is three-quarters the 625size of dimension text. 626 627Vertical justification for tolerances is specified by :attr:`dimtolj`: 628 629=================== ==================================================== 630:attr:`dimtolj` Description 631=================== ==================================================== 632``0`` Align with bottom line of dimension text 633``1`` Align vertical centered to dimension text 634``2`` Align with top line of dimension text 635=================== ==================================================== 636 637=================== ==================================================================================== 638DIMVAR Description 639=================== ==================================================================================== 640:attr:`dimtol` set to ``1`` to enable tolerances 641:attr:`dimtp` set the maximum (or upper) tolerance limit for dimension text 642:attr:`dimtm` set the minimum (or lower) tolerance limit for dimension text 643:attr:`dimtfac` specifies a scale factor for the text height of limits and tolerance values 644 relative to the dimension text height, as set by :attr:`dimtxt`. 645:attr:`dimtzin` ``4`` to suppress leading zeros, ``8`` to suppress trailing zeros or ``12`` to 646 suppress both, like :attr:`dimzin` for dimension text, see also `Text Formatting`_ 647:attr:`dimtolj` set the vertical justification for tolerance values relative to the nominal 648 dimension text. 649:attr:`dimtdec` set the number of decimal places to display in tolerance values 650=================== ==================================================================================== 651 652Limits 653~~~~~~ 654 655The geometrical limits are shown as upper and lower measurement limit and replaces the usual 656measurement text. It is recommend to use :meth:`~ezdxf.entities.DimStyleOverride.set_limits` method in 657:class:`~ezdxf.entities.DimStyleOverride` or :class:`~ezdxf.entities.DimStyle`. 658 659For limits the tolerance values are drawing units scaled by measurement factor :attr:`dimlfac`, the upper 660limit is scaled measurement value + :attr:`dimtp` and the lower limit is scaled measurement value - 661:attr:`dimtm`. 662 663The attributes :attr:`dimtfac`, :attr:`dimtzin` and :attr:`dimtdec` have the same meaning for limits as 664for tolerances. 665 666.. code-block:: python 667 668 dim = msp.add_linear_dim(base=(0, 3), p1=(3, 0), p2=(6.5, 0)) 669 dim.set_limits(upper=.1, lower=.15, hfactor=.4, dec=2) 670 dim.render() 671 672.. image:: gfx/dim_linear_limits.png 673 674=================== ==================================================================================== 675DIMVAR Description 676=================== ==================================================================================== 677:attr:`dimlim` set to ``1`` to enable limits 678=================== ==================================================================================== 679 680Alternative Units 681----------------- 682 683Alternative units are not supported. 684 685 686.. _dimension_linear.py: https://github.com/mozman/ezdxf/blob/master/examples/render/dimension_linear.py 687.. _standards.py: https://github.com/mozman/ezdxf/blob/master/src/ezdxf/tools/standards.py
