Custom User Shapes and Libraries - nasa/gunns GitHub Wiki

Before you create custom links, spotters and libraries, you should review and understand the following:

Data Compression in Draw.io

Because Draw.io is primarily a web-based app, it does a lot of compression on drawing data. Here is their web utility that can be used to compress & uncompress this data when needed. You shouldn’t need to use this, but we link it here for reference.

  • Their terms ‘deflate’, ‘encode’, and ‘compress’ all mean the same thing.
  • Likewise, ‘inflate, ’decode’, and ‘decompress’ all mean the same thing.
  • Paste a block of compressed text into the window and click the Decode button, or paste a block of decompressed text and click the Encode button.
  • Their compression scheme uses zlib default compression with -15 window size (no header or checksum), and base64 compression. This is a common compression scheme for text data transmitted over the internet. zlib is also used by gzip, for example.
  • We have a python equivalent in gunns/draw/modules/compression.py that our scripts use.

This compression is used by Draw.io in several places:

  • Shape libraries are always compressed.
    • Draw.io won’t open them if they’re uncompressed, and always saves them as compressed.
  • Drawing files are saved by Draw.io as compressed by default.
    • Our python scripts uncompress them when needed, and re-save them in uncompressed form.
    • Drawings can be saved as uncompressed via: File > Export As > XML, then uncheck the Compressed box.
    • Unlike the shape libraries, Draw.io can open drawings either from the compressed or uncompressed forms. This makes it handy for us to source control our drawings in uncompressed form, for easy merging and review of changes.
  • Custom shape graphics (like used by our links & spotters) are compressed in the drawing.
    • You’ll see these compressed blobs in the shape=stencil(blob) field of the style attribute of the mxCell XML element.
    • See XML Schema of GunnsDraw Links for an example.

Creating a Custom Shape Library

First, you should keep your custom link & spotter shapes in a custom shape library for your project. Do not put them in the GunnsDraw libraries, as those are reserved for delivered GUNNS shapes.

You can keep your custom library anywhere you want; we suggest in your project repository along with the drawings that use your custom shapes.

To create a new library, open Draw.io and go to: File > New Library. Give it a file name and save it to your project folder. It will then show up in the shapes panel on the left side of Draw.io. It will be initially empty. Below is a picture of what this looks like after creating an empty ExampleLibrary.xml:

Graphics Standards

Let’s all try to follow these standards for a clean and consistent look to GunnsDraw drawings:

  • Make the default height & width multiples of 10 pts, which is the default grid spacing.
  • Aim for a default size of 40 points for your link. Try not to go smaller than 20, or bigger than 80.
  • All connection points should align with the 10 pt drawing grid.
  • Use primarily black lines on a white background. Draw.io has a Dark mode, but all GUNNS shapes have been made for a white background.
  • Labels should be 12 pt. normal Helvetica font.

Creating a Custom Link

1. Create a custom Draw.io graphical shape:

Decide on what you want the graphic to look like and where the connection points are going to be. Please follow the Graphics Standards above.

Open Draw.io and start a new blank diagram.

Choose an existing shape to start from and put one on the drawing. It will be easier to start with an existing GUNNS link if there is one similar enough to what you want, because it will already have most of the XML that you can just modify instead of creating it all yourself. But you don’t have to start with a GUNNS link; you can start with a built-in draw.io shape.

  • Note that not all shapes are editable — you need to start with a shape that has the Edit Shape button in the Style tab of the Format panel.

Scale the shape to the default size it will appear on the drawing.

  • We recommend sizing it to multiples of the 10 pt drawing grid — this makes it and its connection points snap cleanly to grid, which allows cleaner looking drawings.
  • The Draw.io grid has major & minor grid lines. By default, the minor grid lines are at 10 pt intervals and the major lines are at 40 pts.

Edit the shape graphics, by clicking Edit Shape in the Style tab of the Format panel. Most of how to edit shape graphics is covered in the Draw.io article linked above. In addition, follow these guidelines:

shape element:

  • name: give this a unique name, preferably ‘GUNNS your project name’, e.g. ‘GUNNS TS21 DDCU’. Draw.io doesn’t currently use this name for anything. But in case they ever do, we will benefit from having unique names here.
  • h, w: make this match the height & width of the default shape size on the drawing, in points. This makes it easier to figure out x & y coordinates for how your shape graphics will appear relative to the drawing grid.

connections element:

  • constraint: these define the connection points. Connection points aren’t required, but are strongly recommended for making the drawing look nice. You should create a constraint for every port of the GUNNS link. For links with variable ports, consider adding one or more constraint for the variable ports to connect to. Since the port connection lines define which link port they connect to, these constraints don’t have to be dedicated to a specific port #. Depending on the nature of your link, it may be appropriate for a constraint to be used by more than one port.

Feel free to copy any of our GUNNS shapes. They contain examples of how to do a lot of different things.

Below is an example of editing the shape graphics XML from the Edit Shape button:

2. Update link XML

First view the drawing XML to review what your shape’s XML looks like so far. From Draw.io menu bar select Extras > Edit Diagram.

  • If you based your link on an existing GUNNS link, then it is the object element and it will contain a gunns element, a mxCell element, and possibly one or more gunnsShapeData elements.
  • If you started from a built-in Draw.io shape, then it will only be a mxCell element.
  • Your custom shape graphics are contained in the style attribute of the mxCell element, and are compressed within the shape=stencil() field.

Edit the link’s XML to add all the fields required in the XML Schema of GunnsDraw Links.

  • It is best to edit the drawing XML directly to add all the fields you need. From the draw.io menu bar, select Extras > Edit Diagram. Modify the link’s XML then click OK.
  • You will modify the object and gunns elements, and add, remove or modify any gunnsShapeData elements as appropriate.
  • You don’t need to modify the mxCell or mxGeometry elements.
  • The Edit Data window (right-click on the link and select Edit Data) can be used to add new fields to the object element, but it can’t add or modify the gunns or gunnsShapeData elements.

Below is an example of editing the link’s XML:

A note on required vs. optional ports:

  • GunnsDraw allows you to define each link’s port as either required or not.
  • Required ports require a port connector with that # to be connected to the link, or a fatal error will be output by the netexport.py script.
  • Optional ports do not require a port connector with that # to be connected to the link, but you still can.
  • If an optional port has no connection, it is connected to the network Ground node by default when netexport.py creates the network C++ class.
  • This cleans up the drawing by allowing you to omit a lot of Ground connections that are assumed.
  • We recommend making a port optional if the link requires it to always be connected to Ground.

Update graphics styles via the Format panel.

Test the graphics. Try these things to make sure the link graphics work properly:

  • Set and change the link name (label) and that it displays correctly.
  • Scale the size
  • Rotate
  • Check connector port lines to the connection points
  • Graphic style customizations, such as colors, work as intended

3. Add to a custom library

  • Open the custom library to add the link to.
  • Select the link on the diagram.
  • Click the ‘+’ symbol in the custom library to add the selected link to it.
  • Label the link shape in the library, so that it appears correctly when you hover over the shape in the library.
  • Reorder the links in the library as desired.

Note that Draw.io saves custom shape libraries in the compressed format, and it expects them to be in the compressed format when it loads them. Therefore, we never uncompress the library offline, and instead we just edit it from inside Draw.io like described above.

Creating a Custom Spotter

This process is the same as for making custom links, described above. However, note these conceptual differences between links & spotters:

  • Differences in the XML schema. Review the XML Schema of GunnsDraw Spotters.
  • Unlike links, which hard-code a specific link type to a graphic shape, spotters are intended to be more flexible. They let the user define different spotter types for each instance, regardless of graphical shape.
    • Whereas in the old GunnShow tool, all spotters had to have the same shape, in GunnsDraw this is no longer required. Spotters can have unique shapes. Although we still follow the GunnShow shape convention for delivered GUNNS spotters, you don’t have to for your custom spotter shapes.
  • You can put spotters & links in the same library. We have a separate library for spotters in GUNNS, but you don’t have to segregate them like that.

Updating an Existing Custom Link or Spotter

Sometimes you’ll need to make these kinds of updates to your custom links & spotters:

  • Updating the config & input data
  • Updating the shape graphics

Follow these steps to update your custom links or spotters:

1. Open a blank diagram in Draw.io.
2. Open your custom shape library.
3. Place the link or spotter onto the diagram.
4. Use Extras > Edit Diagram to update the XML for your link or spotter directly, just like you did when you created the shape. When finished, click OK.
5. Add the updated shape to your library by selecting the shape and then clicking the library’s ‘+’ button.
6. Click on the libray’s pencil button to open its editing window.
7. The new version of your shape will be at the bottom and will have an empty label. Click on the empty label field to edit it.
8. At this point the old version of your shape is still in the library, so you’ll want to delete it by clicking the ‘X’ icon in its top right corner.
9. Drag your new version from the bottom to wherever you want it to be in the library order. You can rearrange all of the shapes in the library this way.
10. Click Save to save the updated library.

Below is a picture of step 7, where I’m editing the label of a new Sublimator shape in the GUNNS_Fluid.xml shape library:

⚠️ **GitHub.com Fallback** ⚠️