mirror of
https://expo.survex.com/repositories/expoweb/.git/
synced 2024-11-21 23:01:55 +00:00
Troggle UML class diagram and text
This commit is contained in:
Philip Sargent
parent
f266691baf
commit
6403b7f211
BIN
handbook/i/trogclass-1.jpg
Normal file
BIN
handbook/i/trogclass-1.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
97
handbook/l/trogclass-1.html
Normal file
97
handbook/l/trogclass-1.html
Normal file
@ -0,0 +1,97 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<title>CUCC Expo Handbook: Troggle UML Class Diagrams</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../css/main2.css" />
|
||||
</head>
|
||||
<body><style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
|
||||
<h2 id="tophead">CUCC Expo Handbook - Troggle UML Class Diagrams</h2>
|
||||
<h1>Troggle UML Class Diagrams</h1>
|
||||
<style>figure {font-weight: bold; font-size: small; font-family: sans-serif;font-variant-caps: small-caps;}</style>
|
||||
|
||||
<div class="onright">
|
||||
<figure>
|
||||
<a href="https://yuml.me/mkay2100/edit/Troggle-1"><img alt="Troggle UML Class Diagram" src="../i/trogclass-1.jpg"></a>
|
||||
<br><figcaption>Class Diagram - Essential Level (draft - to be corrected)</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
|
||||
<p>This shows the major "things" in troggle and how they relate to each other.
|
||||
<p>So <strong>a survex (SVX) file</strong> is dated to a particular day during the expedition and usually has between 1 and 3 people associated with it.
|
||||
<p>A <strong>Logbook entry</strong> has several people involved and may relate to a cave. It will be dated to a day during the expedition.
|
||||
|
||||
<h3>Design Diagrams</h3>
|
||||
<p>Analysis of expo and design of troggle is done using three levels:
|
||||
<style>
|
||||
li {padding-left: 0;margin-left: 0;line-height:160%;}
|
||||
ul, ol {padding-inline-start: 1em;}
|
||||
</style>
|
||||
<ol>
|
||||
<li>The '<strong>essential</strong>' or 'real-world' level.
|
||||
<li>The '<strong>specification</strong>' level.
|
||||
<li>The '<strong>implementation</strong>' level.
|
||||
</ol>
|
||||
<p>As anyone reading this has probably been on expo and you might think that we can skip the <strong>real-world level</strong>. Not so: the multiplicities (the number of participants in the association) of the relationships between the different cave survey artefacts can be surprising.
|
||||
<p>The <strong>specification level</strong> is where the action is.
|
||||
This is where we decide which aspects of the real world <em>we will ignore</em> and what <em>extra concepts</em> we need to make things work.
|
||||
<p>So we ignore who is resident at top-camp (even though today we record this religiously because of the tax implications for the GastHof at base). We do need to track the in-computer associations between survex files: the *include tree, what directories they live in, what wallet-directory they relate to, and all the individual survex blocks of survey measurements within each survex file.
|
||||
|
||||
<p>We only need <strong>implementation-level</strong> diagrams for tiny, tricky issues. Python is very clear so serves as its own implementation specification. However Django does need some explanation.
|
||||
<h3>Class Diagrams</h3>
|
||||
<p>A Class Diagram is one the the basic types of structural diagram (as opposed to behavioral diagrams) used to understand complex systems.
|
||||
<ul>
|
||||
<li><a href="https://en.wikipedia.org/wiki/Class_diagram">wikipedia:Class diagram</a>
|
||||
<li><a href="https://www.tutorialspoint.com/uml/uml_class_diagram.htm">UML - Class Diagram</a>
|
||||
</ul>
|
||||
<p>
|
||||
The purpose of class diagram is to model the static view of an application.
|
||||
|
||||
|
||||
<h3>Online free class diagram editor</h3>
|
||||
<p>This diagram was created online using the YUML free software at <a href="https://yuml.me/mkay2100/edit/Troggle-1">https://yuml.me//</a>.
|
||||
<p>
|
||||
You can edit your own version to revise this when it becomes outdated. <br>This is the entire source code that generates the diagram:
|
||||
<pre><code style ="font-size:x-small">
|
||||
// Troggle Class Diagram
|
||||
// ------------------------------
|
||||
|
||||
// Chain elements like this
|
||||
[SVX file]<>-wallet 1..*>
|
||||
|
||||
[Wallet]++-1..*>[Scanned Note]
|
||||
|
||||
[Wallet]++-1..*>[Scanned CentreLine]
|
||||
|
||||
[Scanned CentreLine]++-1..*>
|
||||
[Drawing{bg:turquoise}]
|
||||
|
||||
[People{bg:wheat}]<->
|
||||
[LogBook Entry{bg:violet}]
|
||||
|
||||
[People]1..3<->[SVX file]
|
||||
|
||||
[Cave{bg:cyan}]->[LogBook Entry]
|
||||
|
||||
[Cave]->[SVX file]
|
||||
|
||||
// note:
|
||||
[Cave]-.-[Drawing{bg:turquoise}]
|
||||
|
||||
[Expedition{bg:green}]1<>-1..*
|
||||
[ExpeditionDay{bg:green}]<>-
|
||||
[LogBook Entry]
|
||||
|
||||
[ExpeditionDay]1<>-1..*[SVX file]
|
||||
|
||||
[PersonExpedition{bg:yellowgreen}]1<-1
|
||||
[People{bg:wheat}]
|
||||
|
||||
[ExpeditionDay]1..*--1.*
|
||||
[PersonExpedition{bg:yellowgreen}]
|
||||
|
||||
</code></pre>
|
||||
|
||||
<hr />
|
||||
</body>
|
||||
</html>
|
||||
BIN
handbook/t/trogclass-1.jpg
Normal file
BIN
handbook/t/trogclass-1.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
@ -8,11 +8,11 @@
|
||||
<body><style>body { background: #fff url(/images/style/bg-system.png) repeat-x 0 0 }</style>
|
||||
<h2 id="tophead">CUCC Expedition Handbook</h2>
|
||||
<h1>Troggle Architecture</h1>
|
||||
<style>figure {font-weight: bold; font-size: small; font-family: sans-serif;font-variant-caps: small-caps;}</style>
|
||||
|
||||
<h3>Troggle data architecture</h3>
|
||||
<p>
|
||||
The core of troggle is the data architecture: the set of tables into which all the cave survey and expo data is poured and stored. These tables are what enables us to produce a large number of different but consistent reports and views.
|
||||
<style>figure {font-weight: bold; font-size: small; font-family: sans-serif;font-variant-caps: small-caps;}</style>
|
||||
<div style="display: flex">
|
||||
<div style="flex: 50%">
|
||||
<figure>
|
||||
@ -29,13 +29,20 @@ The core of troggle is the data architecture: the set of tables into which all t
|
||||
</figure>
|
||||
</div></div>
|
||||
<p>
|
||||
ALSO there have been tables added to the core representation which are not anticipated in that document of this diagram, e.g. Scannedimage, Survexdirectory, Survexscansfolder, Survexscansingle, Tunnelfile, TunnelfileSurvexscansfolders, Survey. See <a href="datamodel.html">Troggle data model</a> python code (15 May 2020).
|
||||
ALSO there have been tables added to the core representation which are not anticipated in that document of this diagram, e.g. Scannedimage, Survexdirectory, Survexscansfolder, Survexscansingle, Tunnelfile, TunnelfileSurvexscansfolders, Survey. See <a href="datamodel.html">Troggle data model</a> python code (15 May 2020) and click on the Class Diagram below on the right.
|
||||
<div class="onright">
|
||||
<figure>
|
||||
<a href="../l/trogclass-1.html"><img src="../t/trogclass-1.jpg"></a>
|
||||
<br><figcaption>Class Diagram (draft)</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
<h3>Architecture and purpose</h3>
|
||||
|
||||
<p>Read the proposal: "<a href="/expofiles/documents/troggle/troggle_paper.pdf" download>Troggle: a novel system for cave exploration information management</a>", by Aaron Curtis</em>. But remember that this paper is an over-ambitious proposal. Only the core data management features have been built. We have none of the "person management" features, none of the "wallet progress" stuff and only two forms in use: for entering <var>cave</var> and <var>cave entrance</var> data.
|
||||
|
||||
<h3>Implementation in software</h3>
|
||||
<p><a href="http://www.djangoproject.com/"><img class="onright" src="https://www.djangoproject.com/m/img/badges/djangopowered126x54.gif" border="0" alt="Powered by Django." title="Powered by Django." /></a>
|
||||
Troggle is written in Python (about 9,000 lines including comments) and is built on the Django framework. Before starting to work on Troggle it might be a good idea to run through an initial install and exploration of <a href="https://code.djangoproject.com/wiki/Tutorials">a tutorial Django project</a>.
|
||||
Troggle is written in Python (about 5,700 lines excluding comments) and is built on the Django framework. Before starting to work on Troggle it might be a good idea to run through an initial install and exploration of <a href="https://code.djangoproject.com/wiki/Tutorials">a tutorial Django project</a> to get the Django concepts bedded down - which are not at all obvious and some exist only within Django.
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
@ -34,20 +34,15 @@ Usage is 'python databaseReset.py <command> [runlabel]'
|
||||
|
||||
and [runlabel] is an optional string identifying this run of the script
|
||||
in the stored profiling data 'import-profile.json'
|
||||
if [runlabel] is absent or begins with "F-" then it will skip the :memory: pass
|
||||
|
||||
caves and logbooks must be run on an empty db before the others as they
|
||||
set up db tables used by the others.
|
||||
</pre></code>
|
||||
<p>On a clean computer with 16GB of memory and using sqlite a complete import takes about 20 minutes if nothing else is running.
|
||||
On the shared expo server it can take a couple of hours if the server is in use
|
||||
(we have only a share of it). On your
|
||||
own computer, the first in-memory sqlite pass takes only about 6 minutes.
|
||||
We do this so that typos and data-entry errors
|
||||
are found quickly.
|
||||
<p>On a clean computer with 16GB of memory and using sqlite a complete import takes about 10 minutes now if nothing else is running.
|
||||
On the shared expo server it could take a couple of hours if the server was in use
|
||||
(we have only a share of it).
|
||||
<p>Here is an example of the output after it runs, showing which options were used recently and how long
|
||||
each option took (in seconds)
|
||||
<code><pre>
|
||||
each option took (in seconds). <code><pre>
|
||||
-- troggle.sqlite django.db.backends.sqlite3
|
||||
** Running job Profile
|
||||
** Ended job Profile - 0.0 seconds total.
|
||||
@ -63,8 +58,9 @@ survexblks (s) 1153.1 - 3917.0 1464.1 1252.9
|
||||
tunnel (s) - - 25.5 - 23.1
|
||||
scans (s) - - 52.5 - 45.9
|
||||
</pre></code>
|
||||
<p>The 'survexblks' option loads all the survex files recursively following the <var>*include</var>
|
||||
statements. It can take a long time if memory is low and the operating system has to page a lot.
|
||||
[This data is from May 2020 immediately after troggle had been ported from python2 to python3 but before the survex import was re-engineered. It now takes ~600s in total.]
|
||||
<p>The 'survexblks' option loaded all the survex files recursively following the <var>*include</var>
|
||||
statements. It takes a long time if memory is low and the operating system has to page a lot. This has now been rewritten.
|
||||
<p>(That value of 0 seconds for QMs looks suspicious..)
|
||||
<p>The file <var>import_profile.json</var> holds these historic times. Delete it to get
|
||||
a clean slate.
|
||||
|
||||
@ -37,7 +37,7 @@
|
||||
|
||||
<h2>Proposal #1</h2>
|
||||
<p>We edit troggle to create two ids when resetting: "expoadmin" (the django administrator) and "expo" (to have access to Austrian cave surveys and edit pages). These will both be created by the '<a href="https://docs.djangoproject.com/en/1.11/ref/contrib/auth/">django.contrib.auth</a>' system.
|
||||
Django gives us fine-graned access control settings for admin users so we can ensure that "expo" has the minimum necessary but has <a href=https://docs.djangoproject.com/en/1.11/ref/settings/#file-upload-permissions">file upload permissions</a>
|
||||
Django gives us fine-grained access control settings for admin users so we can ensure that "expo" has the minimum necessary but has <a href=https://docs.djangoproject.com/en/1.11/ref/settings/#file-upload-permissions">file upload permissions</a>
|
||||
|
||||
<p>We remove the 'django-registration' system entirely which reduces the <em>attack surface</em> of troggle - and the enforced deprecation/upgrade process certainly feels like an attack.
|
||||
|
||||
|
||||
BIN
images/style/bg-system.png
Normal file
BIN
images/style/bg-system.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.2 KiB |
Loading…
Reference in New Issue
Block a user