Plandroid Help Documentation

Catalog File Structure

This section describes the structure of the XML catalog files. It is intended for advanced users and is only relevant if you intend to create or edit your own catalog files. You need to be familiar with XML syntax to edit an XML catalog.

The parts that are available for selection in the Parts catalog tab carry all of their information with them, such as part number, price and size etc. This information is stored in an XML catalog file that is located in the product application data directory (on Windows XP this is typically C:\Documents and Settings\All Users\Application Data\DelftRed\Plandroid\Catalog, but this can vary with operating system and computer setup). The catalog file must have the standard XML extension .xml, and must be digitally signed by DelftRed Simulation Technology to authenticate its validity.

XML Structure

The catalog XML file has the root element <catalog>, which has the attribute version, which is the catalog syntax version number (this is not the Plandroid version number). Catalog contains information on the catalog version (name, release date, and expiry date), the manufacturer and their terms and conditions, the currency used, and then the main section - the library of parts.

The Parts catalog tab
Parts tab

The parts catalog library is structured in 3 tiers, just as they are shown in the Design -> Parts catalog tab. The top layer is the part type layer (<partType>), which is the highest level of abstraction, and shown in the topmost window of the Parts catalog (e.g. Diffuser). The part type can contain multiple part sub-type (<subtype>) elements. This is the middle level of abstraction, and is shown in the middle window of the Parts catalog (e.g. Metal Louvre Face). The part sub-type can contain multiple part elements, which contains the list of different product codes and sizes for each individual part (e.g. LFR2525, of size 250x250mm).

PartTypes, Subtypes, and Parts

Any of these catalog elements may contain an attribute for the following properties:

All of these catalog elements must contain sub-elements for the following properties:

And any of these catalog elements may contain sub-elements for the following properties:

PartType and Subtype elements may also have the following attribute:

Inheritance

Unless redefined, a part will inherit the settings for these fields from its parent subtype, which in turn will inherit its settings from its parent part type. For example, if you are defining a part type Diffuser which has the property that it should be installed in the second fix, you can define its fix property just once in its part type definition (at the highest level). All subtypes that descend from Diffuser will inherit that setting and therefore also be defined as second fix, unless they have their own fix property defined otherwise. Similarly, descendant parts will inherit the same setting from their parent subtypes if they don't have their own fix definition. Info fields are not inherited.

Icon Sizes (Image Width and Height)

The image element has the attributes width, and height. These define the size that this icon will have, in mm, when placed on the design canvas. (The image metafile's true size is used in the scaling calculations, not its reported size - these are often different.) If only the width is given, the icon height will be set to the width. The part icon drawn in the Part list view is scaled against its parent sub-type image size. The sub-type image size definition is optional. If it is not given, it is calculated as the largest width and height of all its child part icons.

The size of the top level part type icon has no significance beyond adjusting that icon's aspect ratio in the list view.

Subtypes

A sub-type definition may contain sub-elements for the following properties:

Parts

A part definition must contain sub-elements for the following properties:

A part definition may additionally contain sub-elements for the following properties:

List View Labels

The actual label shown in the part list view is the label, if it is defined, otherwise the size, if that is defined, or else the product code, which must be defined. For example, the list view label for a part may read "100mm sq" as a more convenient text than the size, which may be "100x100mm". The label is shown both in the parts list view, and on the canvas depending on the Options -> Design -> Show labels user options selected.

Part Sizes

The size field is sometimes parsed for various functions, and must be in a strict format of: [prefix]Length[xLength[xLength]]units. The only valid prefix is the engineering diameter symbol: "ø". Different lengths can be specified in different units, but the units suffix should be applied to the last of the series of numbers which are given in that unit. Recognised units (and suffixes) are: millimetres (mm), metres (m), feet ('), and inches ("). For example, sizes may be defined as: 200x200mm, or 200mmx6m, or 8". Combining units for a single length, for example feet and inches, is not supported, neither is specifying fractional units, such as 1/2".

Auto-adding Parts

The element add itself contains one or more sub-elements code. This specifies the product code of a part which, if found in the current catalog, is automatically added to the canvas whenever the parent part is added. If the product code is not found in the current catalog, the part is not added and no warnings are given. The application will recognise and avoid circular dependencies - if a part tries to add one of its own ancestors, that addition will be skipped. Therefore parts which always go together can each be defined to add each other without problems. For example, a supply starter fitting can add its matching return fitting, and that same return fitting can itself add its matching supply fitting. Whenever one of these two parts is added, its matching pair will also be added.

When it is a child of an add element, the code element may have the optional attributes offset_x, offset_y, and top. The offset values specify the distance in mm that the added part should be placed from the parent part (distance to the right is +x, and distance down is +y). Both attributes default to 0. The top attribute is a Boolean (true or false), and specifies if the added part should be displayed on top of the parent part (true) or underneath it (false). The default is true. Added parts will automatically attempt to snap-to any compatible connections within snapping range on their parents before being added to the canvas.

You can also define your own add parts in the Catalog Edits File, and even use the special Auto Add This Part to tool to define them automatically.

Example

The following XML snippet shows an example of the 3 tiers of a part definition:


 <partType name="Diffuser">
    <fix>2</fix>
    <installTime>25.00</installTime>
    <installCost>35.00</installCost>
    <!-- part type image dimensions are arbitrary -->
    <image width="32" height="32">
      <file>Diffuser.emf</file>
    </image>
    <subtype function="face" name="Metal Louvre Face">
      <info>Solid metal construction</info>
      <!-- The subtype image dimensions are optional, and are in mm -->
      <image>
        <file>Diffuser_MetalLourve.emf</file>
      </image>
      <part>
        <code>LFR2535</code>
        <price>20.80</price>
        <size>250x250mm</size>
        <label>250mm sq</size>  
        <info>Face 350x350mm</info>
        <!-- part image dimensions are required, and are in mm -->
        <image width="350" height="350" />
        <add>
          <code offset_y="800" top="false">NKAD25</code>
          <code offset_x="100" offset_y="-100" >F77</code>
       </add>
      </part>
    </subtype>
  </partType>

A/C Units

Air conditioners (function="<unit_type> unit" are somewhat more complex, and should have the following additional sub-elements defined, as they are used to calculate the design air-flows:

The values of output (air flow) and cool (cooling power) are used for checking the design with the Design page toolbar button Check design, and for reporting the supplied air in the zones table displayed with the Show zones table toolbar button.

The following sub-elements may be defined, but are for information only and are not used for any calculations in the program:

Part Functions

The program uses the optionally defined part function attribute to determine how to handle the various parts. Valid functions include (but are not limited to) the following:

Note that a part designated as an outlet should be the terminal part which is connected to ducting, as this part is interrogated for its connector size for calculating airflows. For example, for a plastic vent this is often the part itself, but for a metal vent, this will usually be the neck adaptor.

Manufacturers

Information on the manufacturer of the parts is read from the <manufacturer> data at the <catalog> level, and may be used by the program in automatic ordering, for example. It is also possible to redefine the manufacturer information at any part level. The possible fields are shown in the following example, where only the <companyName> field is mandatory when used in this way:


 <manufacturer>
    <companyName>Company Name</companyName>
    <companyURI>http://www.company.com</companyURI>
    <units>Metric</units>
    <contact>info@company.com</contact>
    <orderEmail>orders@company.com</orderEmail>
    <terms>Terms</terms>
    <warranty>Warranty</warranty>
    <notices>Notices</notices>
    <watermark>
      <file>Image.png</file>
      <hash>Akm5u+S293bxgA=</hash>
    </watermark>
  </manufacturer>

Note that the manufacturer can include their own watermark if they so choose, which will be applied to any design image created using a catalog from that manufacturer. The watermark image is protected by a hash code, which guarantees that it has not been modified in any way.

Connection Definitions

Two parts can snap-to if they each have compatible connectors. Connectors are compatible if they have the same types (that is, the same shape and compatible axes), and they have the same size. Snap-to connection definitions in the XML catalog have information on the shape, size, and location of each connector that is overlaid on the part icon, as shown in the following XML snippet:


 <connector>
    <type shape="Circular" axis="Fixed" />
    <size width="200" height="200" />
    <position x="-200" y="365" angle="180" />
 </connector>

If the width and height are the same, you can specify the width and leave out the height.

The connector shape can be one of:

The Fitting shapes allow you to define connections that can connect to other fittings but not to ducting, such as modular plastic moulded components which snap together.

The axis defines the type of angle at which the parts can connect, and can be one of:

If either connector is Free, the connection will be able to rotate. If both connectors are Fixed, both parts will remain at a fixed angle to each other. A connector that is FixedOrFree will be Fixed if it is mated to a Fixed connector, or Free if it is mated to a Free connector. Two mated FixedOrFree connectors result in a Free connection.

The connector position is defined from the centre of the icon, where x is positive to the right, and y is positive downwards.

Connector Inheritance

Connectors can be defined at the sub-type level, or at the part level. If defined at the sub-type level, all parts of that subtype inherit the given connectors.

A connector's type, size, and position can of course be redefined in a <connector> element for any individual part, however it need not be. If it is not given in the connector definition at the part level, the connector size and position will be automatically calculated from the part <size> string (e.g. <size>500x400mm</size>), and follows the following rules:

Note that a connector can be created for a part either by specifying a <connector> element for the part, or by specifying the <size> element with the size data to be used for the corresponding inherited connection.

The inherited connector position, if it needs to be calculated, is scaled from the part's image size relative to the sub-type's image size. For example, if the current image is half the size of the subtype image, the position of the connectors is half that defined in the subtype connector definition. (If the sub-type image size is not given, the largest part image size belonging to that sub-type is used.) Connector angles are not scaled.

Note that even if a connector is defined at the sub-type level, it can be either fully or partially redefined within a <connector> element at the part level, and the connector properties given at the part level will take precedence. Any connector properties that are not given are either inherited from the sub-type connector, or calculated from the part's properties as described above. Note that if a part has multiple connectors, and some of them redefine their properties and others inherit all of their properties, you should still define an empty connector element (i.e. <connector/>) for those connectors that inherit all their properties. If only some of a Part's connector definitions are given, missing connectors will not exist even if they are defined at the sub-type level. Refer to the provided catalogs for examples of how to define connectors with inherited data.

If a connector has the shape None, then it will result in no connector being defined. No axis needs to be supplied in that case. This is useful for removing a connector that was defined at the subtype level, and would otherwise be inherited by a part.

Multiple Connector Sizes

A connector may be defined with multiple sizes. This allows a single connector to match a range of sizes for a given shape. This can be specified in two ways: from within a <connector> element multiple <size> elements can be defined, or multiple <size> strings can be supplied at the part level. The two methods are equivalent.

If a connector has a negative size, then that connector will match any other connector of the same type.

Flow Analysis Constraints

Note that parts which are defined as outlets should have their connectors to ducting specified as the first connector. The first outlet connector is interrogated to determine how the part is connected to the air supply in analysing flows.

Icon Image Files

All part icons must be in the Microsoft Enhanced Metafile Format (.emf). This is a vector format which gives good resolution at any zoom level. EMF files can be exported from Adobe Illustrator, for example. For a catalog file called MyCatalog.xml, the application will first look for a directory called MyCatalog_Images for the image files to use for the part icons. If the directory does not exist or image file is not found there, the application proceeds to look in the Default_Images directory for the image file. This gives the catalog designer complete flexibility to specify their own part artwork, or to use the default artwork provided. When importing a catalog, the application will look for the <filename>_Images directory in the same location as the catalog file <filename>.xml and also import it and its contents. (If you import an image file by itself, the application will place that file in the Default_Images directory.)

The physical size of the EMF image is unimportant - it is a vector image that will be scaled to the physical size of the part as given in its XML image element. However the file size of the image is important, as a file which is too large will have a detrimental impact on the graphics performance of the application. It is recommended to limit the EMF file size to less than 20 KB, and to keep below 10 KB where possible.

The part type image (but not the sub-type nor part image) may be in either EMF or PNG format. It is normally sized at 32x32 pixels (or smaller), which is the size of the list view icon in the catalog list.

Digital Signatures

To be used by the program, a catalog file must carry a valid digital signature from DelftRed Simulation Technology. If any changes are made to the file since it was signed, the digital signature is rendered invalid. A valid signature authenticates that the file has been checked by DelftRed Simulation Technology for correctness, and guarantees that the catalog data has not been tampered with in any way since it was signed. Contact us at signing@plandroid.com to request signing of your finished catalog.

Testing a Modified Catalog

If you are developing your own catalog you can still test it with the application yourself before requesting our signing services. Plandroid will still read a catalog which has no signature or an invalid signature if both its expiry date and its release date set to the current day, today. For example, if today was 1 March 2012, you should set: 


  <catalogVersion>
    <catalogName>My Test Catalog</catalogName>
    <releaseDate>2012-03-01</releaseDate>
    <expiryDate>2012-03-01</expiryDate>
  </catalogVersion>

The program will still report an invalid or missing signature upon reading your modified catalog, but it can still be used for testing and verification purposes. Again, contact us at signing@plandroid.com to request signing of your finished catalog.

Embedded Watermarks

Plandroid supports embedding a watermark image into a catalog, so that whoever is using that catalog has the watermark image drawn onto their design in a similar fashion to the user-defined watermark option in the Options -> Report tab. (See the Watermark section for more information.) With this option, designs made with parts from a certain supplier can be marked as such. Contact us at watermarking@plandroid.com to take advantage of this service in your own catalog.

Catalog Price Edits Files

The CatalogEdits.xml file contains all the catalog information that has been changed by the user, such as edited prices, price modifiers, etc. You can even add in your own Add Parts definitions to completely customise your own catalog's behaviour. You can choose to keep your edits to yourself, or to share your edits with everyone else on your computer by using the Options setting Costing -> Catalog Edits -> My edits apply to: Me only / All users. If you keep your edits to yourself, no other user can inadvertently change the pricing scheme you are using.

The menu item Tools -> Import New Catalog or Price File can be used to import an existing CatalogEdits file containing the price definitions that you wish to use. Whether this file is applied just for you, or for all users on your computer is again determined by your options settings.

Switching Price Edits Files

You can switch between different price definitions that you have imported from the menu item Tools -> Select Catalogs and then pressing the Set Price Edits button. This will set the catalog prices according to the new Catalog Edits file, which is useful when you have different discount structures for different parts of your business. You can also use the context menu in this window to delete an old edits file, or to save a copy of one so you can edit it manually or give it to a colleague to use as well, for example.

Catalog Edits File Structure

The following example, containing edits information for two parts, illustrates the file structure:


  <catalogEdits Version="1.0">
    <part>
      <code>AC51</code>
      <modifier>0.16</modifier>
      <price>2468.00</price>
      <label>New Label</label>
    </part>
    <part>
      <code>ABC3020</code>
      <price>25.00</price>
      <installCost>50.00</installCost>
      <installTime>30.00</installTime>
      <add>
         <code offset_y="800" top="false">NKAD25</code>
         <code offset_x="100" offset_y="-100">F77</code>
      </add>
    </part>
  </catalogEdits>

The <code> field contains the product code of the part that has been edited, and the subsequent fields contain the new part data. If you need to edit the prices of many parts at once, you may find it easier to go directly to this file and enter all of your pricing information directly with a text editor program, for example.

Note that if the listed item is not present in an active catalog, it will be ignored. Similarly, if a part is modified that has the same product code as another different part in a different catalog, that other part will also be modified if its catalog is loaded. The price currency is assumed the same as in the catalog where the part is defined.

The next section is the How do I? section.

Copyright

Copyright © DelftRed Simulation Technology 2009 – 2011. All rights reserved.

XHTML      CSS     Legal     Privacy