Merge pull request #3754 from netbox-community/2248-svg-rack-elevations

2248 svg rack elevations

Author: lampwins

base_requirements.txt

@@ -82,3 +82,7 @@ pycryptodome
 # In-memory key/value store used for caching and queuing
 # https://github.com/andymccurdy/redis-py
 redis
+
+# Python Package to write SVG files - used for rack elevations
+# https://github.com/mozman/svgwrite
+svgwrite

docs/release-notes/version-2.7.md

@@ -76,6 +76,38 @@ STORAGE_CONFIG = {
 
 ## Changes
 
+### Rack Elevations Rendered via SVG ([#2248](https://github.com/netbox-community/netbox/issues/2248))
+
+v2.7.0 introduces a new method of rendering rack elevations as an [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) via a REST API endpoint. This replaces the prior method of rendering elevations using pure HTML which was cumbersome and had several shortcomings. Allowing elevations to be rendered as an SVG in the API allows users to retrieve and make use of the drawings in their own tooling. This also opens the door to other feature requests related to rack elevations in the NetBox backlog.
+
+This feature implements a new REST API endpoint:
+
+```
+/api/dcim/racks/<id>/elevation/
+```
+
+By default, this endpoint returns a paginated JSON response representing each rack unit in the given elevation. This is the same response returned by the rack units detail endpoint and for this reason the rack units endpoint has been deprecated and will be removed in v2.8 (see [#3753](https://github.com/netbox-community/netbox/issues/3753)):
+
+```
+/api/dcim/racks/<id>/units/
+```
+
+In order to render the elevation as an SVG, include the `render_format=svg` query parameter in the request. You may also control the width of the elevation drawing in pixels with `unit_width=<width in pixels>` and the height of each rack unit with `unit_height=<height in pixels>`. The `unit_width` defaults to `230` and the `unit_height` default to `20` which produces elevations the same size as those that appear in the NetBox Web UI. The query parameter `face` is used to request either the `front` or `rear` of the elevation and defaults to `front`.
+
+Here is an example of the request url for an SVG rendering using the default parameters to render the front of the elevation:
+
+```
+/api/dcim/racks/<id>/elevation/?render_format=svg
+```
+
+Here is an example of the request url for an SVG rendering of the rear of the elevation having a width of 300 pixels and per unit height of 35 pixels:
+
+```
+/api/dcim/racks/<id>/elevation/?render_format=svg&face=rear&unit_width=300&unit_height=35
+```
+
+Thanks to [@hellerve](https://github.com/hellerve) for doing the heavy lifting on this!
+
 ### Topology Maps Removed ([#2745](https://github.com/netbox-community/netbox/issues/2745))
 
 The topology maps feature has been removed to help focus NetBox development efforts.

netbox/dcim/api/serializers.py

@@ -157,7 +157,7 @@ class RackUnitSerializer(serializers.Serializer):
     """
     id = serializers.IntegerField(read_only=True)
     name = serializers.CharField(read_only=True)
-    face = serializers.IntegerField(read_only=True)
+    face = ChoiceField(choices=DeviceFaceChoices, read_only=True)
     device = NestedDeviceSerializer(read_only=True)
 
 
@@ -171,6 +171,18 @@ class Meta:
         fields = ['id', 'rack', 'units', 'created', 'user', 'tenant', 'description']
 
 
+class RackElevationDetailFilterSerializer(serializers.Serializer):
+    face = serializers.ChoiceField(choices=DeviceFaceChoices, default=DeviceFaceChoices.FACE_FRONT)
+    render_format = serializers.ChoiceField(
+        choices=RackElecationDetailRenderFormatChoices,
+        default=RackElecationDetailRenderFormatChoices.RENDER_FORMAT_SVG
+    )
+    unit_width = serializers.IntegerField(default=RACK_ELEVATION_UNIT_WIDTH_DEFAULT)
+    unit_height = serializers.IntegerField(default=RACK_ELEVATION_UNIT_HEIGHT_DEFAULT)
+    exclude = serializers.IntegerField(required=False, default=None)
+    expand_devices = serializers.BooleanField(required=False, default=True)
+
+
 #
 # Device types
 #

netbox/dcim/api/views.py

@@ -2,8 +2,8 @@
 
 from django.conf import settings
 from django.db.models import Count, F
-from django.http import HttpResponseForbidden
-from django.shortcuts import get_object_or_404
+from django.http import HttpResponseForbidden, HttpResponseBadRequest, HttpResponse
+from django.shortcuts import get_object_or_404, reverse
 from drf_yasg import openapi
 from drf_yasg.openapi import Parameter
 from drf_yasg.utils import swagger_auto_schema
@@ -13,7 +13,7 @@
 from rest_framework.viewsets import GenericViewSet, ViewSet
 
 from circuits.models import Circuit
-from dcim import filters
+from dcim import constants, filters
 from dcim.models import (
     Cable, ConsolePort, ConsolePortTemplate, ConsoleServerPort, ConsoleServerPortTemplate, Device, DeviceBay,
     DeviceBayTemplate, DeviceRole, DeviceType, FrontPort, FrontPortTemplate, Interface, InterfaceTemplate,
@@ -28,6 +28,7 @@
 from utilities.api import (
     get_serializer_for_model, IsAuthenticatedOrLoginNotRequired, FieldChoicesViewSet, ModelViewSet, ServiceUnavailable,
 )
+from utilities.custom_inspectors import NullablePaginatorInspector
 from utilities.utils import get_subquery
 from virtualization.models import VirtualMachine
 from . import serializers
@@ -175,13 +176,15 @@ class RackViewSet(CustomFieldModelViewSet):
     serializer_class = serializers.RackSerializer
     filterset_class = filters.RackFilter
 
+    @swagger_auto_schema(deprecated=True)
     @action(detail=True)
     def units(self, request, pk=None):
         """
         List rack units (by rack)
         """
+        # TODO: Remove this action detail route in v2.8
         rack = get_object_or_404(Rack, pk=pk)
-        face = request.GET.get('face', 0)
+        face = request.GET.get('face', 'front')
         exclude_pk = request.GET.get('exclude', None)
         if exclude_pk is not None:
             try:
@@ -200,6 +203,39 @@ def units(self, request, pk=None):
             rack_units = serializers.RackUnitSerializer(page, many=True, context={'request': request})
             return self.get_paginated_response(rack_units.data)
 
+    @swagger_auto_schema(
+        responses={200: serializers.RackUnitSerializer(many=True)},
+        query_serializer=serializers.RackElevationDetailFilterSerializer
+    )
+    @action(detail=True)
+    def elevation(self, request, pk=None):
+        """
+        Rack elevation representing the list of rack units. Also supports rendering the elevation as an SVG.
+        """
+        rack = get_object_or_404(Rack, pk=pk)
+        serializer = serializers.RackElevationDetailFilterSerializer(data=request.GET)
+        if not serializer.is_valid():
+            return Response(serializer.errors, 400)
+        data = serializer.validated_data
+
+        if data['render_format'] == 'svg':
+            # Render and return the elevation as an SVG drawing with the correct content type
+            drawing = rack.get_elevation_svg(data['face'], data['unit_width'], data['unit_height'])
+            return HttpResponse(drawing.tostring(), content_type='image/svg+xml')
+
+        else:
+            # Return a JSON representation of the rack units in the elevation
+            elevation = rack.get_rack_units(
+                face=data['face'],
+                exclude=data['exclude'],
+                expand_devices=data['expand_devices']
+            )
+
+            page = self.paginate_queryset(elevation)
+            if page is not None:
+                rack_units = serializers.RackUnitSerializer(page, many=True, context={'request': request})
+                return self.get_paginated_response(rack_units.data)
+
 
 #
 # Rack reservations

netbox/dcim/choices.py

@@ -105,6 +105,17 @@ class RackDimensionUnitChoices(ChoiceSet):
     }
 
 
+class RackElecationDetailRenderFormatChoices(ChoiceSet):
+
+    RENDER_FORMAT_JSON = 'json'
+    RENDER_FORMAT_SVG = 'svg'
+
+    CHOICES = (
+        (RENDER_FORMAT_JSON, 'json'),
+        (RENDER_FORMAT_SVG, 'svg')
+    )
+
+
 #
 # DeviceTypes
 #

netbox/dcim/constants.py

@@ -55,3 +55,63 @@
     'rearport': ['consoleport', 'consoleserverport', 'interface', 'frontport', 'rearport', 'circuittermination'],
     'circuittermination': ['interface', 'frontport', 'rearport'],
 }
+
+
+RACK_ELEVATION_STYLE = """
+* {
+    font-family: 'Helvetica Neue';
+    font-size: 13px;
+}
+rect {
+    box-sizing: border-box;
+}
+text {
+    text-anchor: middle;
+    dominant-baseline: middle;
+}
+.rack {
+    background-color: #f0f0f0;
+    fill: none;
+    stroke: black;
+    stroke-width: 3px;
+}
+.slot {
+    fill: #f7f7f7;
+    stroke: #a0a0a0;
+}
+.slot:hover {
+    fill: #fff;
+}
+.slot+.add-device {
+    fill: none;
+}
+.slot:hover+.add-device {
+    fill: blue;
+}
+.reserved {
+    fill: url(#reserved);
+}
+.reserved:hover {
+    fill: url(#reserved);
+}
+.occupied {
+    fill: url(#occupied);
+}
+.occupied:hover {
+    fill: url(#occupied);
+}
+.blocked {
+    fill: url(#blocked);
+}
+.blocked:hover {
+    fill: url(#blocked);
+}
+.blocked:hover+.add-device {
+    fill: none;
+}
+"""
+
+
+# Rack Elevation SVG Size
+RACK_ELEVATION_UNIT_WIDTH_DEFAULT = 230
+RACK_ELEVATION_UNIT_HEIGHT_DEFAULT = 20

netbox/dcim/forms.py

@@ -1475,7 +1475,7 @@ class DeviceForm(BootstrapMixin, TenancyForm, CustomFieldForm):
         empty_value=None,
         help_text="The lowest-numbered unit occupied by the device",
         widget=APISelect(
-            api_url='/api/dcim/racks/{{rack}}/units/',
+            api_url='/api/dcim/racks/{{rack}}/elevation/',
             disabled_indicator='device'
         )
     )