fix usage of the VIEWPORT status attribute

Added "status" argument to the factory method, which
should be 2 or greater for usual paperspace viewports.
Until this fix, the status attribute had always the
value "1" if not set by the user and indicated the
"active" viewport, which has a total different
purpose and should exist only once.

Author: mozman

docs/source/dxfentities/viewport.rst

@@ -41,8 +41,8 @@ Inherited DXF attributes :ref:`Common graphical DXF attributes`
         -1  On, but is fully off screen, or is one of the viewports that is not active because the $MAXACTVP count is
             currently being exceeded.
         0   Off
-        >0  On and active. The value indicates the order of stacking for the viewports, where 1 is the
-            active viewport, 2 is the next, and so forth
+        >0  On and active. The value indicates the order of stacking for the viewports,
+            where 1 is the active viewport, 2 is the next, and so forth.
         === =====================================
 
     .. attribute:: dxf.id

examples/paperspace_setup_R2000.py

@@ -138,6 +138,7 @@ def setup_layout2(doc: Drawing):
         view_center_point=(60, 40),
         # how much modelspace area to show in viewport in drawing units
         view_height=20,
+        status=2,
     )
     lower_left, upper_right = layout2.get_paper_limits()
     x1, y1 = lower_left
@@ -166,6 +167,7 @@ def setup_layout3(doc: Drawing):
         view_center_point=(60, 40),
         # how much model space area to show in viewport in drawing units
         view_height=20,
+        status=2,
     )
     layout3.add_circle((0, 0), radius=250)  # plot origin
 

examples/viewport_frozen_layers.py

@@ -59,6 +59,7 @@ def create_viewports(paperspace: Paperspace):
             size=(vp_width, vp_height),
             view_center_point=(50, 30),
             view_height=70,
+            status=2,
         )
         vp.frozen_layers = frozen_layers
         cx += vp_width + MARGIN

examples/viewports_in_paperspace.py

@@ -74,6 +74,7 @@ def create_viewports(paperspace: Paperspace):
         size=(5, 5),
         view_center_point=(7.5, 7.5),
         view_height=10,
+        status=2,
     )
     # scale is calculated by:
     # height of model space (view_height=10) / height of viewport (height=5)
@@ -86,6 +87,7 @@ def create_viewports(paperspace: Paperspace):
         size=(5, 5),
         view_center_point=(10, 5),
         view_height=25,
+        status=3,
     )
     paperspace.add_text(
         "View of Circle Scale=1:5", height=0.18, dxfattribs=txt_attribs
@@ -96,6 +98,7 @@ def create_viewports(paperspace: Paperspace):
         size=(5, 5),
         view_center_point=(12.5, 7.5),
         view_height=5,
+        status=4,
     )
     paperspace.add_text(
         "View of Triangle Scale=1:1", height=0.18, dxfattribs=txt_attribs
@@ -106,6 +109,7 @@ def create_viewports(paperspace: Paperspace):
         size=(15, 7.5),
         view_center_point=(10, 6.25),
         view_height=7.5,
+        status=5,
     )
     paperspace.add_text(
         "Overall View Scale=1:1", height=0.18, dxfattribs=txt_attribs
@@ -116,14 +120,15 @@ def create_viewports(paperspace: Paperspace):
         size=(0.3, 0.15),
         view_center_point=(10, 6.25),
         view_height=7.5,
+        status=6,
     )
     # scale = 7.5/0.15 = 50
     paperspace.add_text(
         "Scale=1:50", height=0.18, dxfattribs=txt_attribs
     ).set_placement((16, 14), align=TextEntityAlignment.CENTER)
 
     vp = paperspace.add_viewport(
-        center=(16, 10), size=(4, 4), view_center_point=(0, 0), view_height=30
+        center=(16, 10), size=(4, 4), view_center_point=(0, 0), view_height=30, status=7
     )
     vp.dxf.view_target_point = (40, 40, 0)
     vp.dxf.view_direction_vector = (-1, -1, 1)
@@ -161,13 +166,9 @@ def make_dxf(dxfversion: str):
     width, height = 24, 18
     m = 1
     if dxfversion == "R12":
-        layout.page_setup_r12(
-            size=(width, height), margins=(m, m, m, m), units="inch"
-        )
+        layout.page_setup_r12(size=(width, height), margins=(m, m, m, m), units="inch")
     else:
-        layout.page_setup(
-            size=(width, height), margins=(m, m, m, m), units="inch"
-        )
+        layout.page_setup(size=(width, height), margins=(m, m, m, m), units="inch")
     # The canvas is defined by the page size minus the margins:
     canvas_width = width - 2 * m
     canvas_height = height - 2 * m

examples/viewports_override_layer_attributes.py

@@ -110,6 +110,7 @@ def create_viewports(paperspace: Paperspace):
     vp_width = 3
     cx = vp_width / 2
     cy = (PAPER_HEIGHT - 2 * MARGIN) / 2
+    status = 2
     for func in (
         original,
         override_aci,
@@ -122,9 +123,11 @@ def create_viewports(paperspace: Paperspace):
             size=(vp_width, vp_height),
             view_center_point=(50, 30),
             view_height=70,
+            status=status,
         )
         func(vp.dxf.handle, doc)
         cx += vp_width + MARGIN
+        status += 1
 
 
 def main():

exploration/render_viewport_to_modelspace.py

@@ -41,6 +41,7 @@ def create_viewports(paperspace: Paperspace):
         size=(5, 5),
         view_center_point=(10.0, 7.5),
         view_height=10,
+        status=2,
     )
     # scale is calculated by:
     # height of model space (view_height=10) / height of viewport (height=5)
@@ -53,6 +54,7 @@ def create_viewports(paperspace: Paperspace):
         size=(5, 5),
         view_center_point=(10, 5),
         view_height=25,
+        status=3,
     )
     psp.dxf.view_twist_angle = 45
     paperspace.add_text(
@@ -64,6 +66,7 @@ def create_viewports(paperspace: Paperspace):
         size=(15, 7.5),
         view_center_point=(10, 6.25),
         view_height=7.5,
+        status=4,
     )
     paperspace.add_text(
         "View Scale=1:1", height=0.18, dxfattribs=txt_attribs

src/ezdxf/addons/drawing/dxf.py

@@ -198,12 +198,13 @@ def setup_paperspace(doc: Drawing, bbox: BoundingBox2d):
         size=(psp_size.x, psp_size.y),
         view_center_point=bbox.center,
         view_height=bbox.size.y,
+        status=2,
     )
 
 
 def add_background(msp: BaseLayout, bbox: BoundingBox2d, color: colors.RGB) -> Solid:
     v = bbox.rect_vertices()
-    bg = msp.add_solid([v[0], v[1], v[3], v[2]], dxfattribs={
-        "true_color": colors.rgb2int(color)
-    })
+    bg = msp.add_solid(
+        [v[0], v[1], v[3], v[2]], dxfattribs={"true_color": colors.rgb2int(color)}
+    )
     return bg

src/ezdxf/entities/viewport.py

@@ -62,16 +62,17 @@
         #      active because the $MAXACTVP count is currently being exceeded.
         #  0 = Off
         # <positive value> = On and active. The value indicates the order of
-        # stacking for the viewports, where 1 is the "active viewport", 2 is the
-        # next, and so on:
+        # stacking for the viewports, where 1 is the "active" viewport, 2 is the
+        # next, and so on. The "active" viewport determines how the paperspace layout
+        # is presented as a whole (location & zoom state)
         "status": DXFAttr(68, default=0),
         # Viewport id: (according to the DXF Reference)
         # Special VIEWPORT id == 1, this viewport defines the area of the layout
         # which is currently shown in the layout tab by the CAD application.
         # I guess this is meant by "active viewport" and therefore it is most likely
         # that this id is always 1.
         # This "active viewport" is mandatory for a valid DXF file.
-        # BricsCAD set id to -1 if the viewport is off and 'status' (group code 68)
+        # BricsCAD set this id to -1 if the viewport is off and 'status' (group code 68)
         # is not present.
         "id": DXFAttr(69, default=2),
         # DXF reference: View center point (in WCS):

src/ezdxf/layouts/layout.py

@@ -414,8 +414,7 @@ def rename(self, name: str) -> None:
         self.dxf_layout.dxf.name = name
 
     def viewports(self) -> list[Viewport]:
-        """Get all VIEWPORT entities defined in this paperspace layout.
-        """
+        """Get all VIEWPORT entities defined in this paperspace layout."""
         return [e for e in self if e.is_alive and e.dxftype() == "VIEWPORT"]  # type: ignore
 
     def main_viewport(self) -> Optional[Viewport]:
@@ -434,16 +433,28 @@ def add_viewport(
         size: tuple[float, float],
         view_center_point: UVec,
         view_height: float,
+        status: int = 2,
         dxfattribs=None,
     ) -> Viewport:
-        """Add a new :class:`~ezdxf.entities.Viewport` entity."""
+        """Add a new :class:`~ezdxf.entities.Viewport` entity.
+
+        Viewport :attr:`status`:
+
+            - -1 is on, but is fully off-screen, or is one of the viewports that is not
+              active because the $MAXACTVP count is currently being exceeded.
+            - 0 is off
+            - any value>0 is on and active. The value indicates the order of
+              stacking for the viewports, where 1 is the "active viewport", 2 is the
+              next, ...
+
+        """
         dxfattribs = dxfattribs or {}
         width, height = size
         attribs = {
             "center": center,  # center in paperspace
             "width": width,  # width in paperspace
             "height": height,  # height in paperspace
-            "status": 1,  # has by default the highest priority (stack order)
+            "status": status,
             "layer": "VIEWPORTS",
             # use separated layer to turn off for plotting
             "view_center_point": view_center_point,  # in modelspace
@@ -546,6 +557,7 @@ def add_new_main_viewport(self) -> Viewport:
             size=size,  # I don't get it, just use paper size!
             view_center_point=center,  # same as center
             view_height=vp_height,  # view height in paper space units
+            status=1,  # main viewport
         )
         if len(self.entity_space) > 1:
             # move main viewport to index 0 of entity space
@@ -770,9 +782,9 @@ def paper_units(value):
             size=(vp_width, vp_height),  # I don't get it, just use paper size!
             view_center_point=center,  # same as center
             view_height=vp_height,  # view height in paper space units
+            status=1,  # main viewport
         )
         main_viewport.dxf.id = 1  # set as main viewport
-        main_viewport.dxf.status = 2  # AutoCAD default value
         main_viewport.dxf.render_mode = 1000  # AutoDesk default (view mode?)
 
     def get_paper_limits_r12(self) -> tuple[Vec2, Vec2]:

tests/test_01_dxf_entities/test_141_layer_vp_override.py

@@ -148,6 +148,7 @@ def vp1(self, doc):
             size=(5, 5),
             view_center_point=(7.5, 7.5),
             view_height=10,
+            status=2,
         )
 
     @pytest.fixture(scope="class")
@@ -158,6 +159,7 @@ def vp2(self, doc):
             size=(5, 5),
             view_center_point=(7.5, 7.5),
             view_height=10,
+            status=3,
         )
 
     @staticmethod