otko/docs/QUICK_GUIDE.md

OTKO Quick Guide

A practical, task-first guide to the OTKO desktop GUI. It assumes you have already installed the desktop extras and can launch the app:

pip install -e ".[gui,dev]"
python -m otko

Project files use the .osmodel extension — a single, Pydantic-validated JSON document that diffs cleanly in Git. Analysis output is written separately to *.osresults.h5.

For the layer map and the OpenSeesPy command order, see architecture.md. For the feature-by-feature plan, see roadmap.md.

1. A cantilever walkthrough

This follows the bundled examples/cantilever.osmodel model: a 5 m horizontal beam, fixed at the left end, with a tip load. If you would rather build it by hand, the steps are below.

1. Start a project. File → New (3D Frame). Pick display units in the bottom-right Units combo before typing any values.
2. Lay out a grid. Define → Coordinate System/Grids… (Ctrl+G). Define X lines at 0…5 m (say, every 1 m), Y = 0, Z = 0, and set the grid as the active coordinate system. The 3D canvas will draw it as reference geometry.
3. Add nodes. Define → Add Node… (Ctrl+N), or use the Draw Node tool and click on grid intersections at (0,0,0) … (5,0,0).
4. Define material and section. Define → Material Library… (Ctrl+Shift+M) then Define → Section Library… (Ctrl+Shift+S). The example uses a steel ElasticSection named W12x40.
5. Draw the element. Assign/Define → Draw Frame (F2), then click from the first node to the last. Assign the section with Assign → Frame → Section….
6. Add the support. Select the node at x = 0 and use Assign → Joint → Restraints… (Ctrl+R); restrain all six DOF. The support icon confirms the fixed end.
7. Add the load. Select the tip node and use Assign → Joint → Point Loads… (Ctrl+L). The example applies -10 kN in Y. Alternatively build the distributed case with Assign → Frame → Distributed Load….
8. Set up and run the case. Analyze → Cases… (Ctrl+Shift+A) to create or review a Static case, then Analyze → Run… (F5). The bundled file already contains Tip-Load, Uniform-Load, and a modal Modal-3 case.

Smoke check

Open examples/cantilever.osmodel, run the Tip-Load static case, then Display → Show Force Diagram… → M3. The moment diagram is linear and peaks at 50 kN·m at the fixed end. V2 is a constant -10 kN along the span. If you see that, the model, runner, and post-processor are wired up correctly.

2. Running a modal analysis

1. Open a model that has mass assigned (the bundled cantilever lumps mass at every free node so modal works out of the box).
2. Analyze → Cases…, add or select a Modal case, and set the number of modes n_modes (the example uses 3).
3. Analyze → Run… (F5). Results appear in the results/report panel: periods, frequencies, and participation factors per mode.
4. Display → Animate Mode Shape to view each mode. Use the mode selector and the animation controls, and Export… if you want a video of the mode shape. On the Plotly backend the Play button runs the animation inside the viewport (plotly frames); on PyVista it is driven from Python.
5. Modal results also feed the response-spectrum case: define a response spectrum, then run the SRSS or CQC combination and open Display → Show Response Spectrum.

3. Reviewing results and exporting a report or script

After a run, the results/report panel shows a summary for the active case (static reactions and forces, modal periods, and so on). Use the display actions to inspect the model visually:

• Display → Show Deformed Shape — with a scale slider. The deformed shape is coloured by displacement magnitude with a colourbar, and Display → Show Undeformed Reference overlays the original shape for comparison.
• Display → Show Force Diagram… — axial (P), shear (V2/V3), moment (M2/M3) diagrams.
• Display → Show Pushover Curve, Show Time-History, Show Hysteresis as applicable.

Nodal and distributed loads are drawn as arrows whose length scales with the load magnitude; each load pattern gets its own colour and hovering an arrow shows its value. Support symbols show which translation directions are restrained.

To hand the analysis to someone else, or to archive exactly what was run, export a script:

• File → Export OpenSeesPy (.py)… — writes the full model, and optionally a selected analysis case, as a runnable Python script.
• File → Export Tcl (.tcl)… — the same model as classic OpenSees Tcl.

The export dialog lets you choose "Model only (no analysis case)" or one of the configured cases. The generated script follows the runner's fixed command order (wipe → model → node → fix → … → analyze), so it reproduces the analysis outside the GUI.

4. Changing display units

Use either control, they are the same setting:

• The Units combo in the bottom-right of the status bar, or
• Options → Set Display Units…

Changing units updates how lengths, forces, and moments are formatted in the UI and plots. It does not rescale the underlying model numbers — pick the right unit system before you type values, and convert deliberately if you switch later. A set of unit labels is available in the unit-label tests under tests/unit/test_unit_labels.py.

5. Undo and redo

Every model mutation goes through the undo stack, so most edits are reversible:

• Edit → Undo (Ctrl+Z)
• Edit → Redo (Ctrl+Y / Ctrl+Shift+Z)

Menu text is dynamic — it names the operation, for example "Undo Add 4 Nodes". Compound operations such as drawing a frame (node + element) are wrapped in a single macro, so one undo removes the whole step. File loads, analysis runs, and display-only changes are not model mutations and are not undoable.

6. Navigating the 3D view

Both canvas backends (Options → Canvas Backend) use the same VTK-style mouse bindings, and Help → Mouse Controls lists them in the app:

• Rotate — left-drag.
• Pan — Shift + left-drag, or middle-drag.
• Zoom — right-drag, or the mouse wheel.
• Spin (roll) — Ctrl + left-drag.
• Select — left-click a node or element; Ctrl+click or Shift+click adds to the selection. A drag moves the view; only a click without movement changes the selection.

View presets: Ctrl+1 isometric, Ctrl+2 top (XY), Ctrl+3 front (XZ), Ctrl+4 right (YZ), Ctrl+E zoom extents. The camera keeps Z up, so the horizon stays level while you orbit.

Where to go next

• architecture.md — MVVM layering and command order.
• roadmap.md — what is done and what is planned.
• examples/ — 20+ verified models, each generated from a checked-in Python script.
• ../CONTRIBUTING.md — setup, rules, and verify commands.