Professional Documents
Culture Documents
Hazmap3D User Manual 20 02
Hazmap3D User Manual 20 02
02
USER MANUAL
Ref: HZ01.4358
Feb 2020
Company Information
Micropack (Engineering) Ltd
Fire Training Centre, Schoolhill, Portlethen
Aberdeen, AB12 4RR, Scotland, UK
Tel: +44 (0) 1224 784055
Fax: +44 (0) 1224 784056
Email: [email protected]
Registered in Scotland. Company Registration Number: SC170022.
An ISO 9001:2015 Certified Company. FPAL Registered.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 2
1. Introduction ........................................................................................................................... 6
1.1. Welcome ................................................................................................................................... 6
1.2. The Origins of Fire and Gas Mapping ........................................................................................ 6
1.3. The Rise of 3D Mapping ............................................................................................................ 7
1.4. Changes in v2.01 to v2.07 ......................................................................................................... 8
1.5. Changes in v2.08 to v2.12 ......................................................................................................... 8
1.6. Changes in v20.01 ..................................................................................................................... 9
1.7. Changes in 20.02 ....................................................................................................................... 9
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 3
5. The Mode Toolbar ................................................................................................................ 30
5.1. Viewing/Navigation Mode ...................................................................................................... 30
5.2. Drawing Mode......................................................................................................................... 30
5.3. “Add Fire Detectors” Mode .................................................................................................... 32
5.4. “Add Point Gas” Mode ............................................................................................................ 32
5.5. “Add Beam Gas” Mode ........................................................................................................... 33
5.6. “Select Within” Mode ............................................................................................................. 33
5.7. Paint Mode .............................................................................................................................. 33
5.8. Ruler Mode.............................................................................................................................. 34
5.9. The Layers Slider ..................................................................................................................... 34
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 4
10. Reporting ........................................................................................................................... 54
10.1. How to print (Print Dialog) .................................................................................................... 54
10.2. Top page ................................................................................................................................ 55
10.3. Detector details ..................................................................................................................... 56
10.4. Plan view ............................................................................................................................... 58
10.5. Grademap ............................................................................................................................. 59
10.6. Layers .................................................................................................................................... 60
10.7. What about 3D Screenshots? ............................................................................................... 60
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 5
12.5.10. Translate(dx,dy,dz)....................................................................................................... 89
12.5.11. Units(n)......................................................................................................................... 89
12.6. Arithmetic Expressions.......................................................................................................... 90
12.7. Comments ............................................................................................................................. 90
12.8. Preprocessor ......................................................................................................................... 91
12.8.1. #define XXXX tttttt ......................................................................................................... 91
12.8.2. #undef XXXX ................................................................................................................... 91
12.8.3. #if <numeric expression> ............................................................................................... 91
12.8.4. #elif <numeric expression> ............................................................................................ 92
12.8.5. #else ............................................................................................................................... 92
12.8.6. #endif ............................................................................................................................. 92
12.8.7. #ifdef <symbol>.............................................................................................................. 93
12.8.8. #ifndef <symbol> ........................................................................................................... 93
12.9. The Text Editor. ..................................................................................................................... 94
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 6
1. Introduction
1.1. Welcome
Welcome to HazMap3D, Micropack’s graphically based hazard assessment software. This software
is the culmination of Micropack’s decades of experience in the hazard assessment and detection
business.
That first PC program was called FDA (Fire Detector Assessment). It was written in Turbo Pascal 4.0
(for DOS) and, as far as we know, it was the first software of its kind. The news, however, soon
spread and Micropack started providing similar services to other companies. Following on from
this success, we have seen the rise in similar methodologies being used widely in the hazardous
industries, with subtle improvements over the years which Micropack has also incorporated. We
also now see independent guidance from organisations like the ISA, the influence of which can
again be found in Micropack mapping tools.
The first version of the FDA software used low resolution 320x200 2D colour coded images of the
flame detector footprints, and a same resolution “grade map” plan view of the site to be assessed.
Detector footprints needed to be hand tailored – added masking – if there was significant
obstruction of the field of view of a detector.
In 1995 the software was rewritten in 16bit C as a Windows 3.1 application. Picture resolution
increased to 640x480. In 2001 FDA was rewritten again, now as a 32bit C Windows application. A
Gas Detection module was added around this time and the software name changed to FDAGDA.
In 2004 it was rewritten yet again, this time to remove the last remnants of DOS (no more 8.3
filenames, much higher resolution graphics), file management was now built in, and a high quality
reporting module was added. No more text file output and screenshots! We were no longer
constrained by PC RAM, so image resolution increased to 2400x1800, which at 200dpi was around
the maximum resolution that a colour printer of the day could handle.
Thereafter changes have been gradual. The 2D FDAGDA software continues to be used to this day
as a simple and clearly understood tool for expressing detection coverage in a given area.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 7
1.3. The Rise of 3D Mapping
Over the years it had been suggested several times that a move to 3D modelling might be a good
idea. Generally speaking the idea was rejected as being impractical: too much work, too much PC
compute power required, no access to 3D models, no in house expertise in 3D modelling (and any
such expertise would be expensive to clients), no obvious way to present the results
advantageously on a 2D sheet of paper, etc.
However, quite recently, what used to be considered high end (gaming) graphics cards have
dropped radically in price, so that high quality 3D real-time rendering is possible on the most
mundane of office PCs, and a market for 3D hazard modelling has developed.
Micropack therefore decided in 2015 to whole-heartedly accept the challenge of the largest
update so far to FDAGDA, and incorporate 3D visualization features which would be practical and
useful to engineers – not just be another pretty picture generator (but yes, we do that too).
We hope you appreciate our efforts. And, although we cannot commit to a public timeline, we
believe you will enjoy the many improvements we have planned for the coming years.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 8
1.4. Changes in v2.01 to v2.07
HazMap3D is now a 64bit application. We have also revamped the 3D rendering engine to make it
much faster and better able to handle larger models with ease. Unfortunately these changes have
made it necessary to drop support for Windows XP and Vista hosts, along with all 32bit hosts.
HazMap also now supports a new “Network Floating License Server” activation model, in addition
to the existing node locked activation model.
HazMap now supports an internal library of gas detectors, just as it previously maintained an
internal library of flame detectors. The gas detector model has no affect on assessments, but it
does allow assessments to show an accurate “bill of materials”.
The appearance of the “Detector Details” page(s) on printed reports has been significantly
improved.
The software now has a check for impingement on open path gas detector “beams” by the
background geometry.
A new “Manage Detectors” item is now available on the menu when you right click an assessment
node.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 9
1.6. Changes in v20.01
A most obvious change is that we have switched to a date based versioning system: the major
version is the year, the minor version is the month (01=January). The date is aspirational,
something we aim for. It is not necessarily the literal date of the release, though it should be
close.
The next major change is the addition of a new “Toxic Gas Assessment” feature, which is broadly
similar to the previously existing [flammable] Gas Assessment function. The main difference is that
each toxic gas detector is designed for a specific species of gas, and you must select the species of
interest when performing assessments. Also the goal of toxic gas assessments is to protect human
occupied areas and walkways rather than equipment.
Support for the text variant of FBX has been added, as has support for extracting colour
information from FBX files.
Two new methodologies have been added: Kuwait Oil Company (KOC)(2019) and Petronas (2015).
The icon toolbar (on the main window below the menu bar) has been significantly improved, with
many more relevant functions added.
New feature: cross section planes, allowing the user to more easily see inside closed structures
and also take cross section screenshots.
The CAD draw feature has two new tools: in addition to the pre-existing polygon extrusion tool
you can now draw corridors (e.g. escape routes for toxic gas assessments) and boxes.
Assessment dialogs now have a “Draw Graphically” button which allows you to graphically indicate
the extents of the assessment volume. No more having to switch back and forth between the
dialog and the ruler tool.
HazMap now includes a built-in solid modelling script language called HMGL (HazMap Graphics
Language) which is editable in a built in text editor, which is another new feature. Shapes created
by HazMap are now stored as HMGL files which can then be tweaked as required by the user. You
can even create entire 3D models using HMGL.
The slider on the right hand toolbar has been upgraded. You could previously use this to hide
upper layers of the assessment slices from view. Now clicking the top endstop switches to a mode
whereby only one slice at a time is shown. This allows you to more easily see the details of that
slice.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 10
2. Getting Started
2.1. System Requirements
HazMap3D can run on any PC running Windows 7 (64bit) or later, with a dual core processor and
4GB RAM or better (16GB recommended). You will also need a good quality graphics card which
includes OpenGL 3.x drivers or better. These days any good gaming graphics card has everything
we require. Upmarket business graphics cards such as AMD FirePro or Nvidia Quadro are ideal.
The graphics chipset built into the motherboard may or may not be suitable.
For data storage you will require a disk drive with several GB of free space. The HazMap software
itself requires very little space, but 3D model files can get quite large.
A good quality mouse can be a great boon, since navigating around a 3D space can be stressful on
the buttons and scroll wheel of a cheap mouse (and its owner). Again, gaming mice tend to be a
good choice for this: much better quality then your typical generic PC mouse, and not really that
much more expensive. Look for a mouse without the weird shapes and extra buttons that gamers
sometimes go for. At the time of writing (2017) the author has found the “SteelSeries Rival 100”
mouse to be very good. There is no need to install extra gaming drivers, the standard Windows
mouse driver is fine for HazMap3D.
We would be surprised if the software was practical to use without a mouse, e.g. using only a
trackpad or touchscreen.
HazMap3D started out as a 32bit application, though it was rebuilt as a 64bit app for v1.60 when it
became clear that clients needed to handle larger models than we assumed. If sourcing a new PC
to run HazMap3D then we would suggest quad core with 8GB RAM and a large disk drive as the
minimum spec. The software has been tested and runs well on Windows 7 64bit through to
Windows 10 64bit (Home vs Pro vs Enterprise edition doesn’t matter).
If the software came as bare files then you don’t need to unpack anything, just run the installer.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 11
There follows a dialog box in which you can choose the installation folder. We suggest that you
stick to the default, i.e. just click next. SSD users should not be concerned: the HazMap3D
executable files are not large, and the location of these will not affect where project data files are
stored.
If you chose the larger download which included examples then the latter will be installed in your
“My Documents” folder. A shortcut to run the software will be placed on your desktop.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 12
2.3. Activation (and Deactivation)
The HazMap3D software will need to be registered with the activation server before it can be
used. The first time you run the software the main window will not appear, instead you will be
taken to the “Software Activation” dialog box which requests your licensing details: name,
company and product key. Enter those details very carefully, or better yet paste them in from the
activation email. Then click the “Activate now” button.
Note that activation will require an Internet connection, so do make sure that you are connected
to the internet before you try this. If all goes well then you’ll get a success message and the main
application window will appear. You are now ready to load your first HazMap3D project.
If your PC is behind a corporate proxy server then you may find that activation fails, because
HazMap3D is blocked from being able to access the Internet. In that case you can click the
“Network” button which brings up a supplemental dialog box, as shown below.
You should also be aware that the HazMap activation server will not accept activation from inside
a VM (Virtual Machine). Obviously it would be pointless to attempt to lock software to a virtual
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 13
hardware signature. This has recently become more of a problem because Microsoft has begun
enabling Hyper-v by default in Pro and Enterprise editions of Windows 10. Many users do not
realize that if you have Hyper-v enabled then the Windows 10 user interface is itself running in a
VM.
A new feature in HazMap3D v2.0 is the ability to use a “Floating License Server” as an alternative
to the single PC activation described above. How this works is that instead of each copy of the
software being “node locked” to a particular PC, and therefore only usable by one person, we
instead supply special server software which can be installed on any PC on your local network; it
does not have to be a dedicated server PC, but it cannot be a VM. The Floating Server application
itself must be activated and is always node locked to the PC it is installed on, but once that is done,
any PC with access to the same network can access a dynamic pool of license “seats”, which are
borrowed and returned to the pool as various instances of HazMap3D are opened and closed.
These client versions of HazMap can be installed in a VM if you wish, though graphics performance
may suffer.
In the current Micropack charging structure the cost per seat of a floating license is somewhat
higher than that of a node locked license. However, several people can share a floating seat, so
floating licensing can end up being a more cost effective and convenient solution in a scenario
where a team of people each need occasional access to the software.
To use the Floating Server option you select the “Network (Floating)” option in the “Software
Activation” dialog discussed above, and also enter the server name and port number of the server,
then click “Activate Now”. If a working server app is found at the given network address then
HazMap3D will be activated. If you don’t understand these instructions then no problem, any
good IT support person will.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 14
2.4. Trial (Time Limited) Versions of HazMap3D
Micropack currently sells HazMap3D licenses as annual, 6 month or 3 month subscriptions. This
means that HazMap3D installations are almost always time limited: trial versions typically allow 14
days, and annual subscriptions are 365/366 days. If the time remaining to expiry for the currently
activated product key is less than 30 days then a caption will appear on the HazMap3D upper
toolbar.
The 30 day warning gives you plenty of time to renew the subscription. If you have the 14 day trial
then this panel is always visible. The panel background will change to red if you have less than one
day left.
Contact [email protected] to request a subscription renewal. Note that extensions are added
to your old expiry date, so you don’t lose days by renewing early.
Note for the curious: the days remaining counter relies on your PC’s date/time and clock being set
correctly. If your PC clock is not set correctly then the days remaining caption will be wrong,
however the remote activation server will still disable the product key at the proper time (i.e.
adjusting the clock in your PC will not affect the activation server and hence will not extend the
subscription or the trial).
None of this applies if you are using the floating license option. Software configured to access a
floating license network server can be installed on as many different PCs as you like.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 15
2.6. Loading an example project
The first time you view the File menu it will look like this :-
If you chose the download which included the example projects then the “recent files list” at the
bottom of the menu will already be populated with those projects. Just go ahead and choose one.
“Testground” is a bare bones project using the Micropack (MEL) test ground (beside our
Portlethen office) as the area to be assessed. The test ground 3D model was created using
SketchUp 2014.
“Tutorial One” is a fuller assessment of the MEL test ground, based on the same background
model.
“Tutorial Two” is an assessment of a fictional oil platform. This platform 3D model was created in
SketchUp 2015, and consists of around one million polygons. Models used in HazMap should
ideally be in the 0-4 million polygon range for minimal lag and reduced risk of overflowing graphics
card RAM. Happily the size of the model has little influence on the time taken for an assessment
calculation. Of course these comments assume a current PC with a newish graphics card. We do
not recommend using this software with very old graphics cards.
You may now wish to jump ahead to the “Navigating Within the Model” chapter, and learn how to
move around, rotate, zoom and so on within the example models.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 16
2.7. The Project Panel
The Background folder lists all of the 3D model files you have
imported into the current project. All of the models in this
folder will be visible (if checked) and will also be selectable
with the mouse. Right-clicking the drawing files inside this
folder brings up a submenu with some features which you
may find especially useful, for example export (to drg3d
format), export to obj, and object recolour.
Assessment folders contain the details of a particular assessment. You can have many types of
assessment folder (Fire and Gas are currently supported), and you can have many named variants
within each type. For example the two assessments in the picture shown were both named
“Proposed Layout”). Quite often you might have “Existing”, “Proposed”, and so on.
Assessment folders contain a list of detector definitions appropriate to the type of assessment
(e.g. fire or gas) being carried out. If an assessment has been performed then the folder will also
include a results XML link. In each case if the element is checked (all the way up the hierarchy)
then an appropriate visual representation of the object will be visible in the scene. Like grade
volumes, detector shapes (e.g. fire cones) are not selectable with the mouse (if you try to grab a
detector cone it is actually the background geometry that is grabbed). The base level checkbox
also controls whether that item will be involved in the next assessment or not.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 17
Please note: the visibility checkboxes are not always rigidly honoured, but this is not a bug. For
example, when you first do an assessment the result will be displayed even if it is contained in a
folder which is unchecked and therefore should be hidden from view. The intention is that you
don’t have to enable the entire hierarchy in order to make the new information visible, because
the view can then become so cluttered that it is hard to understand. Likewise if you toggle the
visibility checkbox of an assessment result that is inside a hidden folder.
The first field is “Project Name”. The wizard will automatically create a folder of this name in your
“<documents>\HazMap3D Projects” folder path1. This will also be the name of the project file
located in this folder. The “HazMap3D Projects” folder will be created if it doesn’t already exist.
Next up is “Background Geometry”. This refers to the 3D model to be used as the background for
assessments. We talk more about 3D model formats in chapter 3. For the moment all you need to
know is that a copy of this 3D model file is copied into the project folder, to ensure that a project
can’t be broken when the original model file is deleted, moved or modified. Also see the
“Scale/Clip Options” sub-dialog, which allows you to specify the source drawing units, or to clip
the model to reduce the number of polygons.
1
You can force a different default project path by defining a HAZMAP_PROJECT_FOLDER environment variable. For example, you may want to use
this feature to locate the HazMap3D projects container folder on a shared network server.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 18
Methodology allows you to choose which methodology to apply. Having this on the wizard should
hopefully stop you from applying the wrong methodology by accident!
Click OK, wait a few moments, and the project window should appear and you’ll be ready to start
work.
However, if you need more flexibility in project creation then you can use the File|New Project
(Expert mode) option. This option does almost nothing automatically. It creates an empty project,
and it is up to you to name it, pick a home folder, save the project control file, and add links to
geometry files.
If possible, we recommend either use the wizard or at least do the same as the wizard does: create
your project inside a folder, and locate the folder itself inside your “<documents>\HazMap3D
Projects” parent folder. Having the project files in a predictable location will make them easier to
find and manage.
Note that when you import external CAD files as geometry (outside of the wizard) then the project
only stores a link to that file (like a URL) - no copying is done. Future management of the project
will be a lot easier if all of the linked files are contained in the project folder. The easiest way to
ensure that, after importing the CAD file, is to right click it and choose “Export…”. The export
feature writes the CAD file back out again, in your project folder, and uses Micropack’s proprietary
3D CAD format (.drg3d): the first benefit of the latter format is that it will load significantly faster
than other formats, because we don’t have to spend any time checking for compatibility issues
and bad models. Another benefit is that this allows you to save implicit and explicit changes made
to the model, for example scaling changes, clipping unwanted geometry, and recoloured objects.
Once your background is set you will be able to add assessment folders and then add detectors to
those folders. Please see the Fire Assessments and Gas Assessments chapters for details of how
you do this.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 19
2.10. Detector Management
If you right click an assessment branch in the project hierarchy then you’ll see an item on the
menu called Manage Detectors. The screenshot below shows what the resulting dialog box looks
like when you try this on the Tutorial 2 fire assessment case.
The purpose of this feature is to let you apply actions to groups of detectors, as this is faster than
performing the equivalent operations one detector at a time.
There is a column of checkboxes to the left. These let you choose which detectors an operation
will be applied to. The three buttons in the “Select:” group at the bottom left of the dialog provide
other ways to toggle or (de)select the checkboxes.
The Change Detector Type button lets you change the type (manufacturer and model) of the
selected detectors. The Change Sensitivity function likewise lets you change the sensitivity of
selected detectors.
The Cut and Copy buttons allow you to copy detectors to the clipboard (in the Cut case the
detectors are removed from the current assessment). The Paste button allows you to paste in
compatible detectors from the clipboard. Using these features it is easy to split assessments or to
copy or move detectors between assessments.
Use the Apply button to make all of the preceding changes permanent, although you can still
reverse them using the Edit|Undo menu item if you change your mind.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 20
3. 3D Model Formats
3.1. Native 3D Model formats
HazMap3D has two native 3D model formats, Drg3D and HMGL.
Drg3D is for traditional rendered triangle meshes. The purpose of Drg3D is to give HazMap3D a
save format it can use for rendered models it has processed in some way, for example by scaling
or clipping or colour changes. We can save those changes without having to overwrite a third
party file, or worrying about whether the changes will be compatible with third party applications.
HMGL was introduced in HazMap3D v20.01, and represents a model built using the HazMap
Graphics Script Language (see chapter 12).
.FBX files come in binary and text variants, both of which are supported. FBX files are complex and
somewhat more verbose than other types, however the format seems to be gaining wide
acceptance (e.g. export to binary FBX is provided as an option in NavisWorks Manage, SketchUp
Pro supports export to the text variant. The format can also be imported into popular free
software such as Blender).
.OBJ (Wavefront) files are almost always text rather than binary, so not as compact, and since the
generating application can choose the number of digits to print after the decimal point, they are
usually not as precise either. Colour information is included, so pictures can still look nice as long
as you don’t zoom in too far. OBJ is a good and simple workhorse format supported by almost all
3D graphics packages.
.3DS (3D Studio) files are compact and precise (because they are binary), and they also retain
colour information, which helps if you want the pictures to look impressive. And let’s face it, we all
do.
.STL (Stereo-lithography) files can be used as a last resort. Standard .STL files do not include colour
information1, so if you export to this format then colours and textures will be lost. STL has text and
binary options, and the latter would be preferred, however there are technical reasons2 why STL
can never have the precision of the other supported formats, even if you find the binary variant.
1
There is an unofficial extension to binary form STL which provides colour information, and HazMap does support this
extension.
2
STL files don’t share vertices between polygons, so polygons which should meet at a common edge sometimes don’t,
due to slight rounding differences between vertices.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 21
Micropack may implement support for other import formats in future, but please bear in mind
that the proposed format must meet a number of requirements :-
1. It must be an open format, i.e. we have to be able to get the specification from
somewhere, and we are not currently prepared to incur large licensing fees – which have
to be passed on to all our clients – just for the privilege of adding one additional format
that most clients do not need.
2. It must be an actual 3D format, not a container format. Many of the apparent 3D formats
you may see being talked about or used (e.g. dwf) are actually just containers similar to zip,
and inside that container would be a drawing in some actual 3D format – and that’s what
we would have to support.
3. It should ideally be a proper 3D format, not a 2D CAD format with an additional dimension
added. 3D CAD formats are designed to put lines in precise places, and it is up to the user
to form lines into connected polygons and solids. True 3D formats put 3D solids in precise
places, in fact they do so precisely enough that the object can be fed into an automated
manufacturing process. This type of model is far superior, because you can’t have oddities
such as missing lines, shapes that have no volume etc. SolidWorks is an example of a solid
modelling tool with a very good reputation, but it is rather pricey. The Pro version of
SketchUp has tools for working with solids, and with a bit of care taken can be quite
suitable.
For our purposes a good model is one in which the model consists exclusively of triangles (it has
been “triangulated” or converted into a mesh). Each triangle will be accompanied by a “surface
normal”, i.e. an arrow that points directly out from the side which is supposed to be visible. In
many 3D formats the surface normals are optional (i.e. they would be pointless in a wire frame
model), but a solid model can’t always be rendered properly if we don’t know what side of each
polygon is supposed to be visible.
By convention the three vertices in each triangle will be defined in anti-clockwise order, as seen
from the viewing side. If this is known to be true then we can generate the surface normals
internally. We say that the triangle should have an anti-clockwise “winding order”. Each edge
should have exactly 2 adjacent faces (if it has fewer then there are holes in the model).
Strange things start happening if the model is not manifold. For example, how would you go about
calculating the volume of a cube if only 7 out of 8 faces have been defined? This “cube” has an
infinite volume, and computers are not very fond of dealing with infinities.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 22
3.4. The importance of scale
Internally, HazMap3D uses millimetres as the unit of scale, although the user interface can present
coordinates in meters or feet, depending on the preferred reporting units selected in the Project
Rules dialog.
It’s important to use consistent units for everything, otherwise detector ranges will be all wrong,
and you won’t be able to mix and match models in one scene. This isn’t usually a big deal: just
make sure you know what internal scaling units are used in any model you want to export. For
example if you export from SketchUp then the units are almost always inches, even if you used
mm when creating the model. Notice that you must convert to mm even when the original model
is designed in feet and you intend to use feet in printed reports.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 23
3.5. Tips on Exporting from a Master CAD Model to HazMap3D
We anticipate that many clients will want to export a 3D model from a CAD package to one of the
import formats supported by HazMap 3D. Your CAD package will most likely offer several options
for the exported file, and in this section we offer advice on which options would make the model
most suitable for use in HazMap 3D. Don’t be concerned if your CAD package doesn’t offer all of
these options, these are all “nice to have” rather than essential.
Export Format: FBX if possible, then 3DS, OBJ, or STL – in that order of preference. We support
text or binary variants of STL, text and binary variants of FBX, we support only the binary variant of
3DS, and only the text variant of OBJ.
Units: mm. HazMap 3D can convert scales when loading the model, but it makes more sense to
just do it once, as loading should be faster if it isn’t necessary to apply a scale function.
Triangulate: yes. HazMap 3D can convert quadrilaterals to triangles itself, but your CAD package
might do it in a way you prefer.
Export all or selected: all. Actually this would depend on what you want to be in the exported
model, but if the software defaults to selected then do make sure that the important parts of the
model are indeed selected!
Export double sided faces: no. HazMap 3D does not expect the model to define both sides of a
face, in any case this is not required since HazMap v2.x already renders all faces double sided.
Export colours and textures: yes. HazMap 3D can use colours if provided, and it makes the
pictures look nicer.
Export lines: no. HazMap 3D is only interested in polygons and shapes that have volume, as only
these can influence the field of view of a detector. HazMap cannot even display unconnected lines
(edges that are not part of a polygon), so they have no benefit, but there is a low risk that they
might cause problems.
With typical 2019 office PC hardware the maximum practical size of a 3D model is between 2 and
4 million polygons, depending on how well your PC’s graphics acceleration works. If the model is
too big and slow then you might want to investigate whether your CAD package has the ability to
simplify the model by merging polygons. If not then MeshLab is free, supports all of the above
formats, and definitely has a mesh simplification function.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 24
3.6. Adjusting Geometry Coordinates After The Event
Sometimes you find that you need to adjust the coordinate system used by a model after the
event. This is especially irksome of you’ve already done half the assessment work before anyone
notices!
HazMap provides two features which can help solve this problem.
This first is to double click the background model filename in the project hierarchy, and correct the
scale values used. You can then re-export the model to make the change permanent.
The second solution is to choose the Edit|Move Objects menu item. This brings up the following
dialog box:-
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 25
4. Navigating Within the Model
4.1. Initial view
Here is an example of an initial view when you first open a project :-
You see the now-familiar project hierarchy on the left, and a view of the background model.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 26
4.3. Zoom
In fact HazMap3D doesn’t really have a zoom in the sense of having a function which makes pixels
larger. Instead it has a function, which we may as well continue to call zoom, which really just
moves the camera closer to the thing we would like a better look at.
To use the Zoom function, just use the mouse cursor to point at a selectable object in the scene
and move the mouse’s scroll wheel forward. Imagine a line (a vector) which runs from your eye
(the camera) to the object you are pointing at: for each forward click of the scroll wheel the
camera moves along that vector by a fixed fraction of the distance between the old position and
the object. Result: the object appears larger.
You can go in reverse too, just move the mouse wheel backwards instead of forwards. The
procedure is exactly the same except that the camera reverses along the eye vector. The camera
orientation doesn’t change, so you will still be looking at the same object from a bit further away.
A nice thing about this function is that since the step size is proportional to how far away your
target is, you’ll find that you can zoom quite quickly on an object no matter how far away it is, and
furthermore your risk of overshooting the object is nil, at least until you get very close.1
The zoom function does have a certain minimum step size it applies, otherwise you would never
be able to pass through walls for example. However, you can override this by pressing the shift key
while zooming. The shift key tells the zoom function to microstep (step forward by a much smaller
fraction of the remaining distance).
This zoom function has another subtle but important side effect: by pointing at an object you are
implicitly telling the software that you are interested in that part of the scene. When you come to
rotations you will discover that you actually seem to orbit around that implied point of interest.
4.4. Rotate
To rotate you press and hold down the left mouse button while you move the mouse. The scene
will rotate in accordance with the mouse movement. Actually what happens is that the camera is
orbiting at a fixed radius around your most recent zoom location. If you haven’t zoomed yet then
you will be orbiting around the centre of gravity of the model.
You can also rotate by pressing down the scroll wheel (a.k.a. the middle mouse button). This
method is slightly more awkward to use, but has the benefit of still working when you are using a
CAD mode that reserves the left mouse button for something else (i.e. when drawing simple
shapes for gas grading etc.).
1
Note that if you point at nothing then the camera will travel at a default speed which may be much slower. So, point
at a nearby target if you want to zoom in faster.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 27
4.5. Translate
Translation when you first encounter it will seem similar to rotation. However with translation the
camera moves parallel to the viewing window, you are not orbiting around anything. To translate
the camera you press the right mouse button while you move the mouse. Translation is perfect
when you zoom in on a spot and then wish that the camera was just a teeny bit to the left.
4.7. Selection
If you double click on part of the background model, it will turn blue (actually light cyan). This
indicates that it’s selected. When you come to grading you’ll find that selection is important for
choosing what volume you want to grade.
By the way, please understand that just because you know that all of those facets are part of the
same object, that doesn’t mean that the software knows, and it doesn’t mean that that
information has been encoded in the model. The reason we have implemented several forms of
selection is that it is actually quite hard to satisfy a human being’s intuition of what should be
considered a single object.
Smart selection: this is where you double click on a face in the scene, and the software tries to
infer what other parts of the scene you would consider to be part of the same object. It does this
by first finding all the faces which share edges on the face you selected. Then it finds more faces
which share edges with those faces … and so on. Eventually we hope that a closed shape is
completed, otherwise the function runs out of memory and gives up. All the faces it found will
turn blue. We find that this selection method works the best, most of the time.
Object selection: this is where you press Ctrl+Click on a face, and the software checks the model to
see what object that face belongs to, then highlights the entire object. In a good model this will
give almost identical results to smart selection. Unfortunately it relies on the model designer
having remembered to make every face a member of an appropriate object list, and it turns out
that designers often skip this step, because it has no effect on rendering. Quite often you’ll find
that the only reason objects were created at all was so that the designer could paint them all at
once with the same colour.
Face selection: this is like an emergency fallback selection method. If you press Alt+Click on a face
then only that face is selected.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 28
All of the selection methods above in fact toggle the selection state. I.e. if the face is already
selected then doing the same thing again will unselect it.
Select within: this is where you use the button on the “Mode Toolbar”, and then you draw a
rectangle around the faces you wish to select (click once to start drawing the rectangle, click again
in a different position to complete the rectangle). If you draw the rectangle from left to right then
the HazMap3D viewer only selects objects which fall wholly within the rectangle. If you draw the
rectangle from right to left then any object which intersects the rectangle will be selected.
You need to be careful when using “select within”. The 2D rectangle you draw on the window
defines an infinitely long pyramidal frustum when projected into the 3D scene, and selection
affects any polygon which finds itself inside that frustum. For example, if you draw the selection
rectangle on a wall, then selection might affect the wall, and lots of things behind the wall that
you can’t see and weren’t thinking about. Happily you don’t have to worry about objects behind
the viewer being selected: only objects in front of you can be included.
Select by colour: we’ll describe the colouring tool and associated colour dialog later, but one of the
features it enables is to select all of the objects in the model which match the currently selected
colour.
Selection is cumulative: you can select additional objects after you select the first.
You can deselect everything by double clicking on empty space, pressing the ‘Esc’ key, or you can
choose the Edit|Select none menu option.
The Edit|Select toggle menu option toggles the selection state of every selectable face.
Status line info: when you double click a selectable object in the scene, some diagnostic
information about that object is displayed on the status line (grey bar at bottom of window). Much
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 29
of this information is probably only useful to Micropack, but you may be interested in the (x,y,z)
click coordinate given. This can help you estimate distances in the scene.
View | Default to this position: HazMap3D tries to choose a nice default viewing position when a
model is first presented. Unfortunately this position isn’t always as ideal as we would like. For
example you might find yourself behind a high wall, and it can be quite tedious having to move
around this wall every time you reset the camera position. To solve this problem we have added a
function to the View menu called “Default to this position”. Choosing this menu option causes the
software to store the current camera position and orientation as the default. From then on this
position and orientation is restored every time you reset the camera position.
If you come to regret choosing that position then you can either choose a new position, or else
choose the “View | New camera” function, which will discard your camera preference and restore
the automatic default.
Note that the preferred camera position is stored as a per-project preference. You must save the
project file in order to make the preference stick. Other projects are not affected.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 30
5. The Mode Toolbar
On the right side of the viewing panel is the Mode Toolbar. The software would be a lot
easier to use if it didn’t need modes, unfortunately there are just too many operations to
squeeze onto a couple of mouse buttons.
The toolbar consists of a number of “radio buttons”, only one of which can be active at a
time. The raised border indicates the currently active mode. In any mode you can click the
right mouse button to go back to viewing/navigation mode. Apart from the default
viewing mode, all other modes have submodes too. In any submode a right click backs up
to the previous submode (examples will be given), until you reach the starting submode. A
right click when in a starting submode will restore viewing/navigation mode.
Exact behaviour will depend on which radio button is selected in the “Create object of type” panel
on the right. All three options now cause a small HMGL script to be added to the project. This
script can be tweaked (right click, Edit as text) to correct minor positional errors.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 31
Extruded shape: this submode allows you to draw a 2D polygon (a many sided shape) and then
extrude it into the third dimension. To start things off you should click any selectable object in the
scene. Doing so establishes both your starting point and the plane of the 2D polygon you are
about to draw. If you now move the mouse you will see that a line is drawn from your starting
position to the mouse cursor – the line is in the plane of the face you first clicked.
1. Click to fix a further vertex (and fix the current polygon edge) in the same plane.
2. Right click to back up (cancel the last vertex set). If you back up to zero vertices then you
can choose a new plane. A right click when there are already zero vertices cancels drawing
mode altogether.
3. Double left click to set and indicate the last vertex.
The function repeats until you either cancel drawing mode (right click until -1 vertices set), or you
double click to indicate the last vertex.
If you continue all the way to setting the last vertex then HazMap3D will take your 2D polygon and
extrude it into the third dimension by adding a second layer of vertices which are offset by
“Height/Offset” amount in the direction of the surface normal of the drawing plane. Put more
simply, if you draw on the ground then the second layer of vertices will be at height
(Height/Offset) above the ground. The resulting 3D object will be added to the project hierarchy
in the selected project folder, and given a colour and appearance which is appropriate for objects
in that project folder.
Do remember that left click can’t be used to grab and rotate the model while in this mode. Hold
the scroll wheel down instead.
This function is currently most useful for adding grade volumes to gas assessments.
Corridor: by corridor we mean a human walkway or passageway. This mode is intended to be used
for grading toxic gas assessments. This drawing mode differs from the last in that you are not
constrained to one 2D plane. You can click anywhere in the scene, each click adding a new 3D
coordinate. If you click on nothing then you are really clicking on the ground plane (z=0). On each
click after the first the software will draw a box shape between the last click and this. The box will
have width and height as set in the drawing mode toolbox and is not aligned with the global axes.
You will find that the feature works best if you try to keep to 90 degree corners, or at least try to
change only one dimension at a time.
Box: this mode is mainly intended to be used by the “Draw Graphically” button in assessment
dialogs. However now that the feature exists it can be used to draw boxes for any purpose.
The first click establishes the x,y,z coordinate of one corner of the box. As you subsequently move
the mouse around you will see that a dashed rectangle will be drawn between the first click and
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 32
the present mouse coordinate. A double click causes that rectangle to be extruded into 3D by the
height specified in the dialog.
At the same time as the cone is added to the scene, a detector node will be added to the project
hierarchy, in the fire detector assessment folder. If no such folder exists then it will be created and
added to the hierarchy. If you have multiple fire assessment folders then the default fire
assessment folder receives the new detector.
The default fire assessment folder is highlighted in bold text. If you have multiple fire assessments
then you can change the default by right clicking an assessment folder and choosing “Make
default” from the popup menu.
The newly added detector will have the same type and model as the last detector in the same
assessment folder. You can modify all detector parameters by right clicking it in the project
hierarchy and choosing “Edit”.
Right click to cancel this mode and return to navigation mode, otherwise we remain in this mode
in order to add further fire detectors.
NOTE: an unfortunate consequence of zooming in close to place a detector is that the camera will
almost certainly end up inside the detector cone. Faces can only be viewed from the outside,
which means that the detector cone will be invisible to you – but you will have seen the detector
being added to the project hierarchy, so you’ll know that something happened. If you want to see
the detector cone then you need to back the camera away a short distance, or use View|Reset
camera.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 33
5.5. “Add Beam Gas” Mode
The button represents “Add Beam Gas Detector” mode, also known as “Add Open Path Gas
Detector” mode. This mode differs from the point gas mode in that you need to select two points
per detector: starting coordinate first, then ending coordinate of the open path. The gas detector
will be added to the current default flammable or toxic gas assessment after the second point is
added.
Ctrl+Click (or double click) to set the starting coordinate or right click to return to navigation
mode. If the starting location is set then you can right click to undo it, or another Ctrl+Click (or
double click) somewhere else sets the ending coordinate. The new beam gas detector is added to
the default gas assessment folder and the software waits for you to add another detector.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 34
5.8. Ruler Mode
The button represents “ruler” or “measurement” mode. This mode allows you to measure
distances between selectable points in the scene. Remember that you can rotate the scene while
in this mode by holding down the scroll wheel while moving the mouse. The screenshot below
gives you an example of the type of information given while in this mode :-
In this above example we have already clicked once to set a starting coordinate (x1,y1,z1), while
the reported (x2,y2,z2) relates the current position of the mouse in scene coordinates. Also given
are the relative distances on each axis, and overall.
Note that there is only one Layers Slider tool, not one per assessment, so if you have
multiple assessment results showing then all of them will adjust the number of visible
layers according to this tool.
A new feature in 20.01 is that if you click the blue box at the top then the box will turn
red, which indicates that you are now in single layer viewing mode. I.e. instead of a stack
of layers, only one layer at a time be shown, per assessment. This can give you an even
better view of the detail in one slice. Click the box again to return to the stacked view.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 35
6. The Colour Dialog
Creating presentations is an important part of the work of most engineers. That the presentation
should be visually appealing is just something we have come to expect in the modern world.
Your HazMap3D presentation begins with the 3D model, and it is an unfortunate truth that this
will not always look very pretty. In many cases the model will completely lack colour, sometimes
because of the physical process used to create the model (e.g. a 3D scanning process), and
sometimes because someone forgot to include colour information when exporting the model from
CAD, or the only available format doesn’t support colour.
6.1. An Example
The Colour Dialog, in conjunction with the paint tool on the mode toolbar, can be used to add
colour to models which have this problem. The screenshot below shows a model of an FPSO that
arrived with no colour information. The colour dialog is shown open and ready for use.
As you can see, the FPSO model is quite impressive, but it would be even more so if it had some
colour.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 36
6.2. Colour Dialog Elements
We first need to understand the elements of the colour dialog, which we make visible by clicking
the “Colours” tab which is above the project hierarchy.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 37
6.3. Useful Techniques
Rather than labour the colour dialog feature much longer, we will just draw your attention to a
number of useful techniques:-
WARNING: Colour changes to a 3D model must obviously be stored in the 3D model file, not in the
HazMap3D project file. However, the 3D model is not saved when you save the project file. The
main reason for this is that we did not want people to accidentally modify their source CAD
models when they do something so innocuous as saving the HazMap3D project. We could have
added an “Are you sure?” dialog, but we know from experience that the user skips right past those
without thinking, or thinking that it refers to the project save operation they just chose. So, the
only way to make your colour changes permanent is to do it expressly, by right clicking the 3D
model in the project hierarchy, and choosing “Export”. This saves a copy of the model in the
project folder, along with any scaling, clipping and colour changes that have been made. You can
do this several times if you keep making changes.
• With the colour dialog open and the Paint tool not selected, double clicking a face in the
scene will cause the face colour to become the current colour in the dialog. A nice variant on
this is to double click a face in the scene (which selects the object and makes that colour
current), and then click the “Select” button on the dialog: now all objects of the same colour in
the model are selected.
• With the colour dialog open and the Paint tool selected, double clicking an object in the
scene causes that object to be painted in the current colour (see Selection 4.7 for a discussion
of what double clicking selects). If the painted face was previously selected then all selected
faces are painted in the chosen colour.
• Note that a single left click on a face while in the paint mode begins a rotation operation. This
is why double clicking is needed to paint the face.
• While the “external colour picker” feature is not currently implemented, you can “import” any
colour you want to use by manually typing the colour values (if you can find out what they are)
into the appropriate (RGB or HSL) numeric boxes on the dialog. Then add it to a swatch for
safekeeping.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 38
6.4. The End Result
The screenshot below shows the same FPSO model after it has had a serious makeover, though it’s
actually quite surprising how quickly this can be done. We think you’ll agree that this result would
impress your client more when you have this in your assessment report.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 39
7. The Project Rules Dialog.
When we drill down to basics, the purpose of HazMap3D is to verify that fire and gas designs
conform to the requirements of the client. In order to do that we obviously need to know what
the clients requirements are. To this end most of the major players in the oil and gas industry
have published standards documents setting out their requirements in a form which can be
examined by regulators and contractors.
Note that these are company standards, not national or international standards. Most national
and international standards are non-prescriptive. They say something along the lines that the
company must adopt good practices and take site and employee safety into account when
designing the site. The company internal standard provides a way to demonstrate to national
regulators that these matters have been taken seriously.
To reach the Project Rules dialog you choose the Edit | Project Rules… menu item. It can also be
quickly accessed by double clicking the root element (“Project”) in the project hierarchy, or you
can click the “Grades” tab just above the project hierarchy (this click opens the dialog at the “Fire”
or “Gas” grades tab, depending on the type of the currently selected assessment branch).
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 40
The remaining fields are minor. “Project name” and “Company name” are just labels for your
printed reports. As to the scary looking ”RHO Equivalent of FM3260 test fire” field, this is there
because there seems to be a general acceptance that whenever fire and gas people get together,
they shalt debate the truth of the assertion that 50 kW (or 10 kW, or 40 kW) equals one square
foot pan fire. In fact this might be the only feedback you’ll get about your assessment. This debate
affects us because it is also industry common practice to refer to fire sizes in kW RHO terms, which
impacts our grading rules and reports. This field allows you to configure the local convention for
the size of an FM3260 test fire when expressed in kW. You should probably be wary of changing
this if you don’t fully understand the impact of doing so, as it does affect the grading rules.
Note that the BP GP30-85:2009 standard is unusual in that it bypasses the kW debate and talks
about “effective distance”, i.e. a function of the detection distance to a square foot pan fire.
The Fire Grades tab lets you define what is meant by each of the (colour coded) fire grades defined
in a scene. You can define up to eight grades, each of which can define two fire sizes (for alarm
and control action).
The purpose of the Fire size for Alarm and Control action should be clear. The former should be
less than the latter. The units used in this column will depend on the methodology selected. In the
case of the example the selected methodology is “Micropack Best Practice”, hence target fire sizes
have been expressed in kW-RHO.
The Votes column gives the minimum number of votes required for control action, for each grade.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 41
7.3. Project Rules: Flammable Gas Grades Tab
The best way to assess gas detection layouts is not yet covered by an industry consensus, hence
HazMap3D caters for several different calculation models, each with variants. None of these
models is intended to provide an accurate simulation of how gas will really disperse on a given
day. All are instead intended to evaluate worst case scenarios, i.e. a gas cloud would do damage if
it was centred here, we don’t care how likely that is, but is it possible, and if so would we detect it
with enough voted detectors to achieve control action?
The “Simple” model assumes that the gas cloud is a simple sphere of a given diameter (often 5
meters). The internal distribution of this gas cloud is unknown, except that all points inside the
sphere are assumed to be above the high gas threshold for point gas detectors on the site. If a
dilute cloud diameter is given (> dense cloud diameter) then this is assumed to model an outer
cloud of dispersed gas. Again the distribution is unknown, but is assumed to be above the low gas
threshold for point gas detectors.
Note that open path gas detectors (beam detectors for short) need to be handled very differently
from point detectors. You can’t just define the beam as a detection “sausage” and say that if the
dense cloud intersects that sausage then you’ll get a high gas alarm. Beam detectors don’t work
that way. They work by measuring obscuration of the beam between a transmitter and receiver,
and hence the beam must pass through a sufficient path length in order to get the necessary
attenuation. It is very possible to get a low alarm or no alarm at all when the beam only “nicks”
the dense cloud. On the other hand it is also possible for a beam detector to give a high gas alarm
if it has sufficient path length through a dilute gas cloud. Failure to account for path length may
lead to coverage calculations which are either wildly optimistic, or wildly pessimistic, depending
on the precise geometry.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 42
Most F&G assessment packages fail to handle beam detectors properly. HazMap3D is one of the
few which does. Beam Impingement Distance is a minimum distance allowed between the axis of
the beam and elements of background geometry. Normally this is a manufacturer recommend
value, stored in the detector library, however if the manufacturer does not specific a value then
the value entered here will be used instead.
The “Dispersion” model is not yet implemented in HazMap3D – if selected it currently does the
same as the simple model. When implemented the intention is that instead of using hard edged
spheres, there would be a smoother dispersion of gas concentration within the sphere from peak
to maximum dilution. We know from our old FDAGDA package that a dispersion model gives
smoother, more pleasing detection contours for beam detectors, however at present none of the
current methodologies call for this variant. It is however called for in GP30-85 variants prior to
2009 which are still used in the industry, hence this function may be attractive to clients who still
prefer the older standards.
The “Spacing only” calculation model is intended for clients whose methodology mandates that
we no longer care about gas clouds, detectors will simply be mounted (say) on a 5m grid.
Unfortunately, we have had private reports of dissatisfaction in the ranks of commissioning
engineers regarding this protocol. While intended to be simple, which is good, it glosses over
several questions which arise in the real world, such as which detection thresholds are to be
configured, whether the space rule applies in all three dimensions (HazMap3D assumes that it
does), and how control action voting should be applied. Nevertheless HazMap3D has support for
this model, and also allows for practical variations of it, e.g. secondary spacing (via the dilute cloud
diameter) to handle redundancy and voting.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 43
7.4. Project Rules: Toxic Gas Grades Tab
Toxic Gas Detectors are mostly point detectors, but there are a few open path detectors on the
market, hence we retain the panel for beam impingement distance and mounting position error.
The Exposure Limits panel is where we get to the meat of what makes toxic gas detection different
from flammable gas detection. We have a list of toxic gases (not exhaustive, these are the gases
we expect to encounter in Oil & Gas Industry assessments), and for each gas we have
recommended exposure limits for short term exposure (STEL) and long term time weighted
average exposure (TWA). Both exposure limits are given in PPM (parts per million).
There are two commonly accepted standard practice documents in the industry which give explicit
guidance on toxic gas exposure thresholds. These are the COSHH (UK), and the OSHA (US)
standards. Click one of those radio buttons to select which standard you wish to follow. If you
don’t want to use either standard then select the “Local/Other” button, which will allow you to
modify the thresholds table as you like.
There is only one toxic gas grade, the details of its definition are identical to the flammable gas
grades panel.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 44
7.5. Project Rules: Assessment Colours
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 45
8. Fire Assessments
8.1. Overview
The fire detection assessment performed by HazMap3D is fundamentally the same as that
performed by the FDA component of FDAGDA. In other words we have a number of sample points
in space to be assessed. For each sample point we calculate the fire size which can be detected at
that point by each of the available fire detectors. Later on we examine the grading rules which
apply to the given sample point and colour code the equivalent assessment pixel according to how
well the defined detection targets were met.
• The sample points are distributed throughout a 3D space, whereas FDA assessed a single 2D
plane.
• FDAGDA used a “representative” plan view of the space projected onto a 2D plane, whereas
HazMap3D describes the scene using true 3D geometry.
• FDAGDA assumed a perfect, horizontally aligned, detector cone shape, according to the
horizontal field of view diagram in the manufacturers data sheet. HazMap3D builds a true 3D
model of the detectors field of view, still according to the manufacturers data sheet, and
allows this “cone” to be aligned in any way.
• In FDAGDA, the technician needs to manually mask out portions of the detector footprint, if
the detector field of view is significantly hampered. There is a small amount of software
assistance provided. In HazMap3D the software automatically tests for assessment samples
which are hidden behind obstructions from the point of view of a given detector.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 46
8.4. Add Grading Volumes
Fire graded volumes can be defined in a number of ways.
• The method which gives the technician the most freedom (and the most work) is to draw the
3D grading shapes in a modelling package such as SketchUp. Of course the model must be in
one of the supported 3D model formats as discussed in section 3.2. You then import the 3D
model into one of the project folders which represents the appropriate grade.
• Similar to the previous option, you can create an HMGL script to describe the volume.
• A third method is to first select an object in the scene by double clicking it, or using one of the
other selection methods discussed in section 4.7. Having selected the object you then choose
a grading option from the Grade menu, after which the software will create one or more
graded volumes around the selected object by applying the appropriate grading rules. The
drawing files created will be stored in a subfolder called “DynGrade”, which will be a subfolder
of the project folder (the folder containing the project file).
• A fourth method is to use the graphical drawing features of HazMap3D to manually create 3D
shapes representing graded volumes, adding them to the appropriate fire grade folder. In fact
for fire assessments this is probably not necessary (the feature is intended for gas), but it is
possible. In 20.01 the resulting graphical elements are created as HMGL scripts, making them
much easier to tweak after creating them.
• The easiest way to create “grade 0” (excluded) volumes is to select an object in the scene and
choose the “Grade|Exclude selected volume from FIRE assessments” menu option. This creates
a tightly fitting closed volume around the selected object(s), which will now be ignored for
assessment purposes.
HazMap3D continues the grade colouring conventions established by FDAGDA, however this is
only done as a visual aid for the user, and in printed reports. In fact the colour of the object
representing a graded volume has no bearing on the assessment calculation. A shape is defined as
representing grade B (for example) by virtue of being included in the Grade B project folder.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 47
The next panel is where you define the assessment volume, the main purpose of which is to fix the
scaling and identify what parts of the scene you are interested in. There is no assumptions that all
defined graded volumes are part of every assessment.
In “Other options” we have “Z steps”, which is the number of horizontal slices you want to take
through the assessment volume (slices will be evenly spaced in the z direction). “Representative Z”
selects which slice(s) are included in the assessment report (a representative grademap is saved
for this slice).
A couple of checkboxes control what else is output at the representative Z level. Finally there is an
option to show a visual representation of the “shoebox” in the 3D view. A box is drawn around the
assessment node icon in the project hierarchy, to let you know that this is the assessment whose
shoebox is currently visible.
Save saves the contents of the dialog but leaves the dialog box open.
Close closes the dialog box. If the changes you made were not saved then they are lost.
Assess does a save, followed by an assessment calculation. You can see the result of a fire
assessment in section 11.10.
Number of detectors: generally this only becomes an issue when the user tries to assess the entire
site at once, with a large number of detectors. And even though detector coverage doesn’t
overlap, the number of detectors will still slow down every assessment, because the software
must still do a calculation to determine that the detector is out of range. Consider if the site can be
broken down into independent areas or fire zones for assessment purposes. This is also good
engineering practice with regard to Fire and Gas coverage analysis.
Number of layers: the assessment time relationship here is linear. If you double the number of
layers the assessment calculation time doubles along with it. So, we suggest that you configure the
assessment dialog for a small number of layers while you are working, then increase it to a larger
number to produce the “proof quality” assessment you’ll include in your report.
HazMap v2.00 and later has a caching feature intended to speed up fire assessment recalculation.
What this does is, having done at least one previous assessment, the results for individual fire
detectors are stored in a cache file called “fda_detectors.reuse” which is located in the fire
assessment folder. Each fire assessment folder has its own cache file. This means that if you
haven’t made any project changes that affect that individual fire detector then there’s no need to
repeat the calculation, we can simply fetch the result of the last calculation from the cache. This is
very convenient if (say) you are tweaking the orientation of one detector to improve coverage.
With the caching feature only that one detector needs to have its coverage recalculated and the
results merged with the others for voting purposes.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 48
You can if you wish delete the cache file if for some reason you want to force the software to
calculate everything from scratch (perhaps you want to time it?).
Yellow Indicates areas which have alarm coverage from at least one detector,
but will require the fire size to escalate before it can reach the voting
threshold for control action.
Orange Indicates areas which have alarm coverage from at least one detector,
but does not have the voted coverage necessary for control action.
Brown Indicates areas in which the target fire size cannot be seen by any
detector, but some alarm action will occur if the fire escalates.
Scores are shown independently for each grade, i.e. each grade (A,B,C,D) used in the assessment
adds an additional row to the assessment score table. The table does not include columns
(colours) if the total for that colour is zero. If you see 0% in every box in a column then you can
assume that the actual score was greater than 0 and less than 0.5%, and was then rounded down
for display purposes.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 49
9. Flammable and Toxic Gas Assessments
9.1. Overview
The Gas Assessment calculation in HazMap3D in virtually identical to that found in FDAGDA, since
the GDA calculation was always inherently 3D. Only the method of getting the data in and out has
changed.
The mode toolbar does not distinguish between flammable and toxic gas detectors. All that
matters is what gas assessment project folder is currently marked as the default. If it’s a
flammable gas assessment then adding detectors adds flammable gas detectors. Otherwise it adds
toxic gas detectors.
• The easiest method is to use the simple drawing features of HazMap3D itself to manually
create 3D shapes representing graded volumes, adding them to the appropriate grade folder.
The simple drawing tool is described in section 5.2.
• A secondary method which may give the technician more freedom (and more work!) is to draw
the 3D grading shapes in a modelling package such as SketchUp. Of course the model must be
in one of the supported 3D model formats as discussed in section 3.2. You then import the 3D
model into the “Grades” parent folder, choosing the appropriate gas grade from the context
menu.
• A third method is to describe the grade volume using an HMGL script.
• The easiest way to create “grade 0” (excluded) volumes is to select an object in the scene and
choose the “Grade|Exclude selected volumes from GAS assessments” menu option. This
creates a tightly fitting closed volume around the selected object(s), which will now be ignored
for assessment purposes.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 50
9.4. Performing a Flammable Gas Assessment
To perform a flammable gas assessment you right click the flammable gas assessment folder name
in the project hierarchy, and choose the Assess… menu option. A dialog box will appear, similar to
the one shown below.
In “Other options” we have “Z steps”, which is the number of horizontal slices you want to take
through the assessment volume (slices will be evenly spaced in the z direction).
“Representative Z” selects the layer which will be included in the assessment report. In fact you
can choose a different layer when printing the report, it is only the grademap which has to be
taken from this layer.
A couple of checkboxes control what else is output at the representative Z level. Finally there is an
option to show a visual representation of the “shoebox” in the 3D view. A box is drawn around the
assessment node icon in the project hierarchy, to let you know that this is the assessment whose
shoebox is currently visible.
Save saves the contents of the dialog but leaves the dialog box open.
Close closes the dialog box. If the changes you made were not saved then they are lost.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 51
9.5. Performing a Toxic Gas Assessment
To perform a flammable gas assessment you right click the flammable gas assessment folder name
in the project hierarchy, and choose the Assess… menu option. A dialog box will appear, similar to
the one shown below.
Assess does a save, followed by an assessment calculation. You can see the result of a gas
assessment on the next page.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 52
In other words it is probably best to keep your assessment shoebox tightly bound around the area
of interest.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 53
9.7. Interpreting the Assessment
Indicates areas which fully meet the graded alarm and control
Green
action requirements.
In methodologies which test only detector spacing this indicates
that the sample is within spacing*0.5*sqrt(2) of a detector. For
example, if spacing is 5m, then green indicates that the sample is
within 3.54 m of a detector.
Orange Indicates areas which have alarm coverage from at least one
detector, but the voting target for control action is not achieved.
This assessment colour cannot occur with methodologies in which
detector spacing is the only assessment criterion.
Red Indicates areas with no coverage.
We should probably clear up one misunderstanding that often arises when attempting to interpret
gas assessments, which is that each sample point in the colour coded result represents the
assessment of a potential gas cloud which centres on the sample point. The volume filled by
assessment samples of a particular colour has very little to do with the volume of the gas cloud. If
we tried to do it any other way then we’d be in trouble, because an infinite number of possible gas
clouds can overlap each sample point, and how would you represent an infinite number of
conflicting results? Happily only one gas cloud can be centred there, so that is the cloud which the
assessment sample relates to.
Scores are shown independently for each grade, i.e. each grade (O, PE) used in the assessment
adds an additional row to the assessment score table. The table does not include columns
(colours) if the total for that colour is zero. If you see 0% in every box in a column then you can
assume that the actual score was greater than 0 and less than 5%, and was then rounded down for
display purposes.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 54
10. Reporting
When the possibility of 3D Fire and Gas Mapping was first mooted within Micropack, one of the
main problems foreseen was that, ultimately, the assessment needs to be rendered in 2D so it can
be printed on a 2D sheet of paper. So, did the 3D preparation steps truly buy us anything?
Certainly we have seen this being a problem in the industry. The assessment reports we have seen
so far from 3D packages have been extremely poor by the standards of FDAGDA (our older
software). It’s hard to see how those collections of cluttered 3D perspective screenshots could be
useful at all to the technicians that have to source, cable and commission the detectors. But,
apparently the industry is willing to accept this lack of precision in order to claim 3D availability.
However, when Micropack chose to enter the 3D arena we were determined to find a way to give
users the best of both worlds: pretty 3D pictures for presentations, and precise 2D representations
for the printed reports, as required by field engineers and technicians.
The Output to RTF option is a “print to file” feature which tells the reporting module to save this
report to a “Rich Text Format” file, in addition to the printed copy. We find it very useful to print
to PDF while at the same time rendering an RTF document which you can open in Microsoft Word.
The RTF document will be written back to the same folder as the assessment xml.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 55
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 56
10.3. Detector details
Below is a sample detector details table from a fire assessment.
This should be mostly self-explanatory. Notice that the Z coordinate is given in ALD (Above Local
Deck) form, as this is what the commissioning technician will expect. In order to calculate this
number the software needs to know what offset should be subtracted from the model Z
coordinate in order to get elevation ALD. You can enter a deck Z offset in the assessment dialog,
in which case it will apply to all detectors in the assessment. Or, if some detectors have different
deck levels then you can enter an offset for that detector only, in the detector properties dialog.
Take care: the detector contributions information is not what we have seen others report in a
similar looking table.
In our table, the “All Detectors” bottom row gives the raw voted coverage for all detectors, for
various voting strategies. Hence this is why the 1ooN (one out of N) total is 75%, which matches
the sum of 53+22 (see the coverage totals in the last row of the coverage summary from the last
section).
The single detector rows tell you how the all detectors best case number is affected if that
detector is eliminated. Obviously a degraded coverage must always be worse then best “All
Detectors Available” case. In a well-designed system there is sufficient redundancy so that a single
detector in fault will not have a significant impact under the selected voting strategy.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 57
The Detector Details page for Gas Assessment reports is similar.
There is no pan and tilt for gas detectors, and open path gas detectors (OPGDs) need two
coordinates. Also Gas voting strategies are typically different because there are two levels of
alarm, i.e. high and low alarms. Still, this table is essentially the same as the fire example.
Notice the red IMPINGED warning for some of the open path gas detectors. You get this warning if
the assessment code detected that the “beam” is obstructed by parts of the background 3D
model. You should fix this and rerun the assessment. If the obstruction is not real (some models
will have people etc in the model to show scale) then the warning can be turned off in the
properties of that detector.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 58
10.4. Plan view
Integral to a 2D presentation of the site is a plan view of the area, as this forms the backdrop and
context for all other information which we superimpose. Rather than have the user supply a 2D
plan view separately, we attempt to derive one from the 3D model. Technically, the “plan view” is
a 2D orthographic projection of those elements of the 3D model which fall inside the assessment
shoebox. The latter caveat is important, otherwise, e.g. on an offshore platform model, you would
never see anything in the plan view except the solid mezzanine deck.
Above is a sample plan view of the Micropack test ground as described by the 3D model provided
with the “Tutorial One” example.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 59
10.5. Grademap
Below is a sample of what we refer to as the grademap, which is one of the print options offered.
In HazMap3D the graded areas are three dimensional, so this grademap is just a representative
presentation through one slice of the model, which should be sufficient for your report.
Note the plan view in the background (dimmed so that the foreground will stand out), which
provides a context for the foreground elements. The latter consists of slices through each grade
volume at the selected z, plus the detector names, positions and orientations.
It isn’t very obvious from this particular drawing, but the grades are prioritized, i.e. the grade A
shape is always shown on top of grade B, which is always shown on top of grade C, etc.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 60
10.6. Layers
Next are the individual layers. HazMap3D assesses a site using a regular 3D grid of samples. All of
the samples at a common Z can be composed into a 2D presentation, and this is what we refer to
as a layer or slice - obviously a 2D slice is easier to print. Below is what it looks like when we print
one of those slices.
Like the grademap, it has the plan view in the background, and the detector positions and
orientations. The only difference is that the foreground has colour coded coverage information.
It may be that no single slice adequately represents detector coverage in the area. In that case we
recommend printing all the slices to RTF, then delete the slices you don’t need from your report.
We hope you’ll agree that this is much easier to understand than a fuzzy perspective screenshot.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 61
11. Example Assessments
A few example projects should have been installed in the “HazMap3D Project Folder” area of your
Documents folder. If for some reason this did not happen, or if you download an updated
examples pack then use File| Install Example Project to install the example projects discussed in
this appendix.
This example projects have been previously generated by Micropack and should make a useful
starting point for those new to Fire and Gas Detection in reviewing what a typical project set up
may look like.
This will also provide sample 3D models around which you can create your own test projects and
assessments. To start a new project and build your own assessments, follow the instructions in the
remainder of this user manual.
To create a new project, open the software and select File, then New (in future the notation
File|New means to do this). It is good practice to name your project as soon as possible, so do
that now using File| Save.
Right click on the Background item in the project hierarchy and select Add 3D Drawing. You will be
presented with the following dialog box:
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 62
ground was modelled in mm, no conversion is required. Note it is important to know exactly what
unit was used in the generation of the 3D model, such that the scale will be correct. This is of
critical importance when modelling the detection coverage. The panel on the right allows you to
clip imported geometry that falls outside a shoebox volume described here, but we will not use
that feature right now (the checkbox should not have a tick in it).
When the background model is imported you will be presented with the following:
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 63
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 64
11.4. Flame Detection Grades
Select the appropriate grade from the drop down menu (along the tool bar on the top of the
screen) to apply this grade to the highlighted equipment.
Once the equipment is graded one or more new entries will appear the Grade branch of the
project hierarchy. These new entries represent drawings which have been created in the
background and added to the project folder (in the DynGrade subfolder). You can rename these
new grades objects in the hierarchy by selecting them there, and then clicking them again when
they are already selected. Then type in new text and press return.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 65
The scene can quickly become cluttered with new grades, detectors and so on. To alleviate this
you can untick the checkbox in the project hierarchy to hide those scene elements. Be careful
about clearing the checkbox at a single item level, as this may cause them to be omitted from the
assessment.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 66
To edit the flame detector, double click on the detector tag on the left hand side tool bar:
To show the flame detector’s true field of view accounting for the obstructions within the area,
check the ‘Show Obstructed Cone’ box:
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 67
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 68
11.6. Flame Detection Assessment
To carry out the assessment, ensure the individual grades and flame detectors are checked, to
make sure they are included in the assessment:
To carry out the assessment, right click on the Assessment file in the project hierarchy, and select
‘Assess’, to bring up the following dialog:
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 69
Note the number of ‘Z steps’ maximum is 20, which
will provide the greatest detail in the analysis. The
‘representative Z’ is that which will appear when
exporting the results into a report, to allow for
engineers to quickly review the results.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 70
Feel free to navigate around the model to review where the blind spots appear and analyse where
detectors can be optimised. Detectors can be added, relocated or removed, then re-assessed to
analyse the impact of detector alterations on the coverage provided.
Remember the percentage coverage is not the most important feature of the analysis, as you need
to consider where the blockages actually occur. This emphasises the importance of an engineer’s
analysis of the detector locations when optimising the detection layout.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 71
11.7. Gas Detection Grades
Gas detection is typically analysed in a volumetric fashion: we no longer want to detect specific
equipment, but rather to protect a volume. The purpose is to test whether significant gas
accumulations could remain undetected.
To grade a volume with respect to gas detection, select the volume creator tool on the right hand
side of the screen. For the purpose of this assessment, the ‘Height/ Offset’ is input as 3m:
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 72
To create the 3D volume, select the corners at ground level of the area you want to cover, and
double click the final corner. HazMap3D will extrude the 2D polygon to create a the 3D volume:
The 3D shape is coloured red because the Target Project Folder (in the yellow dialog box) chose
the PE grade folder. HazMap3D uses red as the default colour for PE grades.
A new item is also added to the project hierarchy on the left of the screen. This has been renamed
as ‘GasVolume’, for ease of reference.
At this point we can then check the appropriate boxes to hide the grade.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 73
11.8. Gas Detector Placement
The Micropack Test Ground has an open path gas detector located as shown in the model below.
We can enter the mode to add an open path gas detector (right hand side of the screen), and
double click on the transmitter, then double click on the receiver, to complete adding the open
path detector:
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 74
This detector can then be edited by double clicking in the detector shown in the project hierarchy:
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 75
To add detectors in new location, simply follow the previous process. The following is the
proposed location for a new OPGD, which will then be added in the assessment:
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 76
A point gas detector is now proposed at the following location, but 2.5m above the ground.
In order to locate the detector within the limitations of the model, enter add point gas detector
mode (right hand side) and place the detector on the ground:
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 77
By entering the detector properties we can rename it, and
raise the elevation to 2.5 m:
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 78
11.9. Gas Detection Assessment
To carry out the gas detection assessment, ensure the
individual grade file and individual gas detectors are
checked. Remember if the folder is unchecked it will
hide them from the field of view, but as long as the
individual files are checked, they will be included in
the assessment:
Right click on the ‘Assessment (Gas/New)’ folder and
select assess. Appropriate properties can then be
inserted. Note the shoebox volume must include the
whole model, but only the graded areas will be
analysed:
Position the camera such that a good angle of the assessment can be viewed, then select ‘Assess’:
As with flame detection, detectors can be relocated, added or removed to analyse the impact this
will have on detection coverage optimisation.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 79
11.10. A More Complex Model
A completed version of the above project can be found in your documents folder as “Tutorial 1”.
Micropack has also provided a second tutorial containing a much more complex platform model,
screenshots from which you will have seen in earlier parts of this user manual.
Contact Micropack if you have any difficulty creating your own HazMap3D projects.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 80
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 81
12. The HazMap Graphics Script Language
12.1. Introduction
To start with: this is easy. You can learn the script language structure in minutes. But how to
explain why we need one? Well here goes.
HazMap has always represented 3D models as polygon meshes. In fact that’s really the only
practical choice for a rendering format given that that’s how the graphics card also represents the
3D model(s). A triangle mesh format is also fine for ray tracing, which means it’s fine for HazMap
assessments too.
But. We keep being asked to include “simple” model editing features, or even the ability to create
models from scratch, and it turns out that triangle meshes are far from ideal for high level editing
purposes. An object that started off as a simple cylinder with length and diameter has since, by the
time it reaches HazMap, become a mesh of hundreds of triangles and now it’s very hard to go back
and manipulate the object as a cylinder.
Hence, we conceived the need for a higher level description of a 3D model, which would retain the
high level information indefinitely even after being rendered to the scene. The high level
representation would of course be optimized for simple engineering applications rather than art
(i.e. designed to handle cylinders and boxes but not for sculpting horse heads).
The user must be able to edit an underlying HMGL description in some way, and a back end would
render the HMGL description to a standard polygon mesh for display and assessment purposes.
HMGL could be created and edited using dialog boxes, though that isn’t really practical if the scene
could contain hundreds or even thousands of objects, each with many details. Or we could try for
some kind of manipulation of the 3D scene itself, but it’s hard to make that intuitive and accurate.
Either or both of those things may happen in time. In the first instance however we have created a
direct representation of HMGL as a script language which can be edited in a text editor, and we
have added a suitable text editor (with syntax checking) into HazMap. HMGL scripts can be
included in a HazMap project just as other model formats can. Certain HazMap functions (e.g.
grade drawing tools) now create HMGL scripts instead of Drg3D files. To edit a script that is
already part of your project you simply right click the HMGL file in the project tree view and
choose “Edit as text”. Currently only one HMGL script at a time can be open for editing: the “Edit
as text” option will be greyed out in that case.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 82
12.2. Origins of the Language
The most direct inspiration for HMGL is OpenSCAD, which is a GPL licensed open source 3D
description language and IDE, primarily used for creating models for 3D printing. HMGL was
however rewritten from scratch with our own goals in mind. The main difference from OpenSCAD
is that the latter is fundamentally designed to do constructive solid geometry (a.k.a. CSG,
constructing objects by the union and difference etc. of simpler solids), whereas HMGL is not: in
HMGL the input solids remain distinct objects. In the future we may add CSG features to HMGL,
but this would be in the form of explicit operators (union, difference etc), it would never be
implicit as in OpenSCAD. The reason for this is that OpenSCAD gets unbearably slow as detail is
added to a model, we assume because of the complexity introduced by CSG. It would be
impossible to use OpenSCAD to handle even a small model of the type that HazMap typically has
to deal with.
Another main difference is that an OpenSCAD script describes a single object (there is one main
function that calls everything else), whereas one HMGL script can describe an entire site.
Obviously both OpenSCAD and HMGL owe some debt to the C programming language for the basic
syntax rules.
The ‘{‘ and ‘}’ characters are used to bracket a group of instructions that must be processed (a.k.a.
compiled) as a unit, though no statements are present just yet. “MyObject” is a placeholder for
any name you give to this object (don’t pick a name that matches one already used by HMGL – if it
turns blue in the text editor then you need to change it). You would see this name if you exported
the model to OBJ format. The empty ‘(‘ and ‘)’ parenthesis indicate that this as a function (a.k.a.
object) and not some other kind of named entity, they also bracket the list of named parameters
that can be passed to this function. However, HMGL does not yet support parametric objects, so
these ‘()’ brackets are for now just placeholders needed for compatibility with future language
versions that may have that feature. For now the ‘( )’ list will always be empty.
Please note that spaces and newlines have no relevance in HMGL grammar rules, provided they
don’t occur inside a token (language element). The tokens in the above example were “MyObject”,
“(“, “)”, “{“, “}”. Any number of spaces, newlines and comments could be added around those
tokens and they would be ignored by the back end compiler that converts the text language to a
working model.
An example of where a space would not be legal is “My Object” (i.e. “My”<space>”Object”),
because that creates two tokens “My” and “Object”, which would causes a syntax error (the
compiler expected the token “My” to be followed by “(“, not by another name token.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 83
Inside the ‘{ }’ brackets can be a sequence of zero or more statements. Statements have the form
verb, verb, verb (as many as you need, including zero), noun, semicolon. Verbs are also called
“directives”, Nouns are 3D primitives such as a Box or Cylinder. Directives (verbs) are used to do
something to the box or cylinder, such as move, rotate, scale or colour it (or all of the above). Any
noun can also be replaced by a group of statements enclosed in ‘{ }’ brackets. This allows one
directive to apply to the entire group – which means you don’t have to type those directives
multiple times.
This creates a box with a corner located at the global origin and having a colour chosen by
HazMap. The dimensions are X=2 units, Y=4 units and Z (height) = 6. There is a declaration you can
make at the start of the script which determines the units used. It looks like this:
Units(METERS);
The semicolon at the end of a statement serves the same purpose as the period ‘.’ in the English
language – but it can’t be a period because that could be confused with a decimal point in a
number, for example 10.
Semicolons are generally optional in HMGL, but it’s good practice to use them anyway just as it’s
good practice to user proper punctuation when writing in English. The practical benefit is that in
the case of syntax errors it gives the parser more clues as to where you intended the next
statement to begin, which allows the location and nature of your error to be more precisely
indicated (parsing is the first step in processing the script: checking that the syntax and grammar
conforms to the rules: this is the step that generates all syntax errors).
Continuing the example: Here is an object consisting of two boxes, plus a directive moving both
boxes by the same amount.
MyObject()
{
Translate(50,50,0) {
Box(2,4,6);
Box(1,4,6);
}
}
I’ll remind you that spaces and newlines have no relevance to the parser. For the benefit of human
readers however it is conventional to indent lines in some manner similar to that shown here, i.e.
“nested” groups of statements inside ‘{ }’ brackets should be indented so you can more easily
identify which statements are part of the nested group, and which parent directive they are
nested inside.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 84
If you need to do multiple things to the same group of objects then you can have multiple
directives. For example suppose we wanted the boxes to be red.
MyObject()
{
Colour(RGB(200,0,0)) Translate(50,50,0) {
Box(2,4,6);
Box(1,4,6);
}
}
The Colour directive (Color is also accepted) takes a single number as a parameter, that number
being the colour value for the object. The above colour directive could have been written
“Color(0x000000c8)”, but that isn’t very readable, so a helper macro called RGB(r,g,b) has been
built into the parser, and that’s what you see above. Hopefully you are already familiar with RGB
colouring from the HazMap Colour tab and other software.
Objects can reference other objects. For example if you wanted multiple instances of your
“MyObject” object:
MyObject()
{
Colour(RGB(200,0,0)) Translate(50,50,0) {
Box(2,4,6);
Box(1,4,6);
}
}
MyObject2()
{
MyObject();
Translate(10,0,5) MyObject();
}
If an object A you create is referenced by another object B, then object A is assumed by the parser
to represent a component – object A will not be rendered except when referenced by other
objects. If an object you define is not referenced by other objects then the object is assumed to
be independent and will be added to the 3D scene as such.
The remaining sections will now give details on available built in object types and directives.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 85
12.4. Built-in Object Primitives.
12.4.1. Box(dx,dy,dz)
This creates an axis aligned box with the given dimensions. The bottom left corner of the box is
placed at the origin.
N_sides is a smoothness parameter – it gives the number of sides which should be used to
approximate the cylinder, and can range from 3 to 90. It can also be set to zero to let HazMap
choose a medium smoothness. Cylinders are one of the more memory hungry shapes, so if you
want your model not to lag then it’s best not to over-do the smoothness parameter, especially
when part of a component that will be referenced many times.
This same primitive can be surprisingly useful at low smoothness parameters. For example an
“n_sides” of 4 is another way to create a box, n_sides of 6 creates a hexagonal nut shape, and so
on.
Essentially this is a pipe connected in a loop, nose to tail. “outer_diam” gives the diameter of the
loop, “pipe_diam” gives the diameter of the pipe it’s made from. The n_sides_pair argument is
actually two parameters packed in to one. You can leave this number set to zero, or you can
calculate nsides_loop*256 + nsides_pipe. Or don’t calculate it – just type it as a constant
expression (discussed later).
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 86
12.4.5. Vessel(length, diameter, cap_type_pair)
This is a specialised shape which is expected to be useful for HazMap 3D models, it creates an
approximation of a cylindrical pressure vessel, complete with appropriately shaped end caps. The
vessel centre is located at the global origin and the vessel axis is aligned with the global x axis.
The only interesting parameter here is the “cap_type_pair” argument. Again this is a double
parameter packed into one number. You can leave this number as zero, or express it as
cap_type(left end) + cap_type(right end)*256. Or don’t calculate it – just type it as a constant
expression (discussed later).
As you can see, the cap type can be expressed independently at each end. Normally this would
not be very useful, but we’ve seen examples of upright pressure vessel shapes which are flat at the
base but have a regular pressure vessel shape at the top.
Both variants provide a list of 3D coordinates, however the VertexList2D version can be used in the
common case where all z coordinates are 0, which saves a bit of typing.
12.4.7. Diameter(diameter)
Again, this is not a real object. This function is intended to be used solely when using the “Pipe”
directive. The latter takes a starting diameter and accepts one or more VertexList children as
objects to process. You can insert Diameter(x) declarations in between VertexList objects to
change the pipe diameter at the next vertex. Do not use Diameter anywhere else! Here’s an
example of a pipe object which includes a diameter change.
Pipe(18,0.2,4) { // 18 sides, 200mm diam, 4 steps per elbow
VertexList([0,0,0],[4.8,0,0]);
Diameter(0.3); // switch to 300mm diam.
VertexList([5,0,0],[5,5,0],[5,5,5]);
}
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 87
12.5. Directives.
Directives are actions that can be performed on objects, whether your own or a built-in type. Note
that although directives are written left to right, or outer to inner, they are applied right to left, or
inner to outer. E.g. :-
Colour(RED) {
Colour(BLUE) Box(1,2,3);
}
This example first creates a box. Then the box is painted blue. Finally the box is painted red,
leaving you with a red box. Obviously you would not actually use such a redundant formulation,
this merely serves to demonstrate the order of processing. This example assumed that the
symbols RED and BLUE have been defined by you using the #define preprocessor directive
described later.
12.5.1. Colour(number)
The alternate spelling “Color” is also accepted. This directive paints all child objects with the given
colour. The number is an RGBA colour code as a single number, or you can use the RGB(r,g,b) or
RGBA(r,g,b,a) macros for a more readable way to express the colour code.
Colours are expressed as a RGB triplets with each component ranging from 0 (off) to 255 (fully
saturated in that colour channel). The RGBA form has an additional component A (alpha) which
expresses the transparency of the object, and in HMGL ranges from 0 (fully opaque) to 255 (fully
transparent). Fully opaque or medium level transparency usually works best.
12.5.2. Corridor(width,height)
Accepts a group of one or more VertexList children and creates a “corridor” along the path set by
the vertices. A corridor has a box shaped cross section, the centre of a box is placed at the vertex
coordinate given, the box has width and height as given. The corridor is not constrained to be axis
aligned.
The corridor directive recognizes when the start and end vertices are the same, in that case it
creates a closed loop of corridor.
12.5.3. Extrude(dx,dy,dz)
Accepts a group of one or more VertexList children each defining a 2D shape, and creates a 3D
shape by “extruding” the 2D shape along the vector dx,dy,dz. The magnitude of this vector is also
the length of the extrusion.
The current extrusion code requires the extrusion vector to be at right angles to the plane of the
2D shape (i.e. you can’t create skewed shapes using this function). If the vector is not at right
angles to the shape then the function will rotate the shape to make it so.
This feature works most intuitively if you create your 2D shapes in one of the basic planes (XY, YZ
etc.), and then extrude along the third axis (Z, X etc.).
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 88
You should be warned that Extrude() is not very forgiving if the vertex list contains errors, such as
describing a self-intersecting polygon. In those cases the object simply will not appear: so if you
make a change and your object vanishes then go back over your list of vertices carefully, because
there must be a mistake. The text editor does try to indicate the more common mistakes, but
there are limits as to what can be done.
12.5.4. Hull()
This directive calculates a shape corresponding to the 3D convex hull of all the vertices of all the
child shapes.
All of the children of the Pipe() directive will be run as one continuous length of pipe, with elbows
and diameter changes as necessary. To begin a new length of pipe just create a new Pipe directive.
The Pipe directive recognizes when the start and end vertices are the same, in that case it creates
a closed loop of pipe.
12.5.7. Revolve(n_steps)
This directive creates a surface of revolution. The children are expected to consist of 2D shapes
drawn in the XY plane. This 2D shape will then be spun around the X axis, as if creating a shape
from a 2D template on a lathe duplicator. As usual, n_steps is the smoothness parameter for the
revolution.
12.5.8. Rotate(rx,ry,rz)
Not to be confused with revolve! The Rotate() directive rotates the child 3D shapes around one or
more of the main axes. Rotations are express in degrees counter clockwise. Rotation around the Z
axis is done first, then Y, then finally X.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 89
12.5.9. Scale(xscale,yscale,zscale)
The Scale() directive allows you to scale an object, applying independent scale factors along the X,
Y and Z axis. Do remember that to leave a dimension unchanged you should scale that dimension
by one, rather than by zero.
A useful trick is to create some object, let’s say a length of girder, and give it a design length of one
unit. The girder object can then be scaled (using Scale(length,1,1) to any dimension required
elsewhere. This avoids the need to have create several versions of the girder that differ only in
length.
12.5.10. Translate(dx,dy,dz)
This directive moves all child objects by the amount given. Note that this is a “move by” operation,
not a “move to” operation. In other words, position changes are cumulative :-
Translate(2,2,0) Translate(2,2,0) Box(1,2,3);
is the same as :-
Translate(4,4,0) Box(1,2,3);
This fact is most useful when creating components. The component function can use Translate and
Rotate to create the desired assembly. Then you can translate the assembly as a whole to
wherever required.
12.5.11. Units(n)
This is a special case directive. It is the only directive which can occur by itself, outside of an
object. If present then it must be at the start of the script file (obviously we don’t care about
spaces, newlines and comments that appear before it), and it can occur no more than once.
Example:
Units(METERS);
If not present then millimetres is the default. The complete list of allowed scale symbols are MM,
CM, METRES (or METERS), FEET and INCHES. Upper or lower case is accepted.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 90
12.6. Arithmetic Expressions
The HMGL parser accepts a numeric expression anywhere it expects a number. The numeric
expression is evaluated at compile time and the resulting value is passed to the script backend.
This can be useful to create “self documenting code”.
For example, the “Vessel” object accepts a compound argument 3 which allows you to select a cap
style for each end of the vessel separately. The formula is cap_type(left end) + cap_type(right
end)*256. Let’s suppose that you want to use cap type 3 at both ends. You could write the Vessel
call like this :-
Vessel(3,1,771);
Vessel(3,1,3 + 3*256);
Now if you wanted to change one or more cap types then you can easily do it without having to
look up the formula and recalculate. Many similar instances will occur.
12.7. Comments
You can if you wish add comments to an HMGL script, this can be helpful if you want to clarify
your intentions. The language supports two kinds of comments. Multi-line and single line.
Multi-line comments start with /* and end with */. For example :-
/* This is a
* multi-line comment.
*/
Note that the parser does not allow one multi-line comment to occur inside another.
Single-line comments start with // and continue to the end of the line. This is the only exception
to the rule that line endings have no relevance in HMGL grammar. For example :-
The parser does allow single line comments inside a multi-line comment.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 91
12.8. Preprocessor
The script language parser also includes support for a preprocessor. Non-programmers don’t
really need to understand what a preprocessor is: feel free to skip this introduction and just jump
straight to a description of the additional language features provided.
A preprocessor stands between the raw text file and the language parser proper. The job of a
preprocessor is to get first look at the stream of language tokens as they are read from the file. If it
recognizes a symbol then that symbol is replaced by another sequence of tokens defined earlier
using a #define directive. The preprocessor also recognises and strips out comments (both the /*
*/ multi-line kind and the “//” single line kind), and its own preprocessor directives.
The HMGL preprocessor is similar in concept but not as powerful as a full C programming language
preprocessor. The main limitation is that you can’t define parametric macros (i.e. #define macro(x)
...), you can only define non-parametric symbol names.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 92
Conditional compilation is a good way to have a section of script that can easily be turned on or
off. For example :-
#if 1
MyObject()
{
Translate(50,50,0) /* a comment could go here */ {
Box(2,4,6);
Box(1,4,6);
}
}
#endif
The “#if 1” conditional obviously evaluates to a non-zero value, therefore the MyObject() section
is passed on to the next stage of the parser. This conditional can easily be changed to “#if 0” to
exclude this section of code.
Of course, you could simply wrap this entire function in a multi-line comment using “/*” and “*/”,
however that is considered poor practice, because the section of conditional code may already
contain a multi-line comment that you didn’t notice (as in fact the above example does), and the
preprocessor does not allow nested multi-line comments (single line comments inside a multi-line
are okay). This could lead to unintended sections of code being enabled.
This issue is admittedly less of a problem in the modern era of syntax highlighted text editors, e.g.
comments in the HazMap text editor will be shown in green. If a comment isn’t green then you
must have inadvertently enabled that code.
12.8.5. #else
This directive can only occur as a clause in an ongoing #if directive. If the previous #if or #elif
clause evaluates to zero, then this is the fallback clause: any language tokens in this section will be
passed unconditionally to the next stage of the parser. The #else clause must be terminated by
#endif. No further #elif or #else clauses are allowed.
12.8.6. #endif
Every #if directive sequence must eventually be terminated by a matching #endif directive.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 93
12.8.7. #ifdef <symbol>
This directive is similar to #if, but there is no numeric expression to evaluate. The conditional
evaluates to 1 (meaning the branch is taken) if the symbol is defined, regardless of value, and
evaluates to 0 otherwise.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 94
12.9. The Text Editor.
The text editor in HazMap is based on Scintilla, the same text editing engine used by Notepad++,
which you may be familiar with. Scintilla is used to implement a standard programming text editor,
complete with syntax highlighting. Text editing features are more or less complete, the only thing
missing is a search and replace function.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 95
13. Troubleshooting
13.1. HazMap installs but refuses to activate on my laptop (no Internet).
If you are on a company network then this almost certainly means that network firewalls are
blocking external internet connections except from specific applications, and HazMap is not one of
them. You must ask your IT people to whitelist “wyday.com” for both http and https traffic. Wyday
are the people who maintain our activation server.
Alternatively you can activate HazMap when you are home. Bear in mind however that HazMap
must check in with the activation server at least every 14 days or the activation will be suspended.
A final option is to contact Micropack (mailto: [email protected]) and ask about our floating
license server option. This was described in section 2.3 of this manual.
Alternatively you can use the floating license server option, as this obviates the need to lock
clients to one PC (the floating server application must still be node locked).
Clipping the model in HazMap itself is possible but doesn’t make the model load any faster (it has
to load the model before it can clip it). However if you re-export a clipped model then the
exported drawing file will be smaller and faster to load.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 96
13.4. Parts of an object disappear as I zoom in on them
... but before I reach them. This problem is greatly reduced in HazMap v1.70 and later, however
the root cause is that the scale must be wrong.
In HazMap the projection window is very close to the camera: a few mm. Call this distance L. The
clipping effect is only possible if the object distance is less than L, which usually means that the
entire object is microscopic, just a few mm across or you wouldn’t have zoomed in so far, hence
the scale must be wrong. Confirm what scales should have been used, and then double click the
model in the project hierarchy in order to change to the correct scale. It is important to use the
correct scale, as otherwise detector ranges will be all wrong.
13.5. Parts of the scene disappear and reappear as I rotate the view
This sometimes happens when you have an assessment result in the field of view, and a
transparent portion of that assessment passes in front of a background object. In essence the
graphics card “depth map” feature gets confused about which object should be visible.
What happens is that the graphics card thinks “no need to render this background object, because
I’ve already rendered something that goes in front of it”. However when that “something else” is
transparent, it should render the background object.
It also has to do with the order in which objects in the scene are rendered – transparent objects
should ideally be rendered last in order to avoid this confusion. However we have seen that it still
happens occasionally.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 97
Completely transparent pixels in an assessment are only possible in ungraded areas. Therefore the
problem is greatly reduced if you avoid having assessment shoeboxes which are very large
compared to the graded volumes they are intended to enclose.
Of course you can also simply turn off the assessment result view if the background model is your
main concern at that moment.
It’s possible that you’ve hit the memory limit on your graphics card. It can only store a certain
number of polygons, though the exact number will of course depend on the card. Models will
zoom and rotate with little or no lag provided the entire model fits in the RAM of the graphics
card. But, as soon as the graphics driver has to start swapping GPU and PC memory then the
graphics speed is going to suffer badly. In fact some graphics card drivers can’t handle it at all and
simply crash (luckily this seems to be rare). This is a case of the straw which broke the camel’s
back, so the difference between super fast and super slow (or crash) may indeed be only a few
polygons. It can only be solved by reducing the model size. See the earlier suggestions on this. If
preparing a model for someone else then our finding is that it is best to aim for between 1 million
and 4 million polygons, and of course the graphics card used must be reasonably modern if you
want to do this kind of work.
Another possibility is that the graphics card is defaulting to a minimum power use profile. At
Micropack we saw horrible performance with an expensive NVidia Quadro P4000 card following a
Windows 10 quarterly feature update. No amount of fiddling with the visible 3D settings made any
difference, however changing the global preset from “Base Profile” to “3D App – Visual
Simulation” suddenly restored top performance again, even though the profile didn’t seem to
have changed any of the visible settings.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.
HazMap 3D v20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 98
13.7. Strange Horizontal Lines Which Flicker as I Navigate
This effect is called “Z Fighting”. It happens when two faces in the model are so close together that
the graphics card can’t decide which one is closest to the camera, and therefore which colour to
paint the pixel. On each pixel row it makes the decision again, and sometimes it chooses one face,
sometimes the other.
Even in a good model the effect is possible due to digital computers having finite numerical
precision, however the most common reason for this problem is a minor error in the model, i.e.
two objects occupying the same space, a condition that cannot happen in reality. In the example
below the cause is a light grey metal base on the box frames with a thickness of 0.
Generally you can simply ignore this problem as it has no affect on assessments.
Copyright © Micropack (Engineering) Ltd, 2019. Reproduction without Micropack approval is prohibited.
HazMap 3D 20.02 User Manual
Ref: HZ01.4358 Doc Rev: 20.02 99
Explanation 2: We have also seen this happen when the object is tiny relative to the scale of the
whole scene. Small rounding errors can create differences in the position of an object in the model
held in PC memory relative to the model stored in the graphics card. In this case the effect will be
that the selection ray misses the intended object and a nearby object is selected instead.
This can happen when there’s a network glitch of some kind, for example if our activation server
goes down for maintenance or if your own LAN server is performing a big backup. HazMap will
allow you to keep on using the software for 14 days before the activation expires, so you shouldn’t
be too concerned by this dialog, unless it persists for more than a day.
Reproduction without Micropack approval is prohibited. Copyright © Micropack (Engineering) Ltd, 2019.