From 3a41070788f6d07c7c46c6f36b8bd08e6c0d185c Mon Sep 17 00:00:00 2001 From: smill Date: Wed, 16 Sep 2026 11:26:20 -0400 Subject: [PATCH] docs: restructure README, redesign logo, move screenshots to docs/screenshots --- README.md | 215 +++++++++------------- docs/logo.svg | 43 +++-- snip3.png => docs/screenshots/grid.png | Bin snip1.png => docs/screenshots/menu.png | Bin snip2.png => docs/screenshots/toolbar.png | Bin 5 files changed, 113 insertions(+), 145 deletions(-) rename snip3.png => docs/screenshots/grid.png (100%) rename snip1.png => docs/screenshots/menu.png (100%) rename snip2.png => docs/screenshots/toolbar.png (100%) diff --git a/README.md b/README.md index 38f1fd9..7a6d53d 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@

- OTKO + OTKO

+

Draw the model. Click run. Read the diagrams.

+

- A SAP2000-style desktop GUI for - OpenSeesPy. - Draw the model, click run, look at the diagrams. + License: AGPL-3.0 + Python 3.10+ + Status: pre-alpha

@@ -14,77 +16,47 @@ --- -![OTKO main window](docs/screenshots/main_window.png) + + + + + + + + + + + +
SAP2000-style cascading menusCompact dark toolbarParametric grid generation
SAP2000-style menusCompact dark toolbarParametric grid wizard
-## Why +## What is OTKO? OpenSees does nonlinear FEM well. Its user interface is a script. -OTKO puts a visual front-end on it: - -- Draw nodes, frames, supports, and loads on a snapped grid. -- Assign materials, sections, and load patterns through dialogs. -- Run static, modal, pushover, and time-history analyses with progress - and cancel. -- Look at the results — deformed shape, mode shapes, force - diagrams, pushover curves, time-history plots, hysteresis loops. -- Save the model as one `.osmodel` JSON file. Diffs cleanly in Git, - builds cleanly from Python. +OTKO puts a visual front-end on top of it: draw nodes, frames, +supports, and loads on a snapped grid; assign materials, sections, +and load patterns through dialogs; run the analysis with progress +and cancel; then read the results — deformed shapes, mode shapes, +force diagrams, pushover curves, hysteresis loops. Underneath, the `core` Pydantic model works fine from a script or -notebook. The GUI is a front-end, not the whole product. +notebook without any GUI. The GUI is a front-end, not the whole +product. -## What works today +## Highlights -- **Modeling** — grids, nodes, frames (elastic + force-based), trusses, - quads, zero-length sections, restraints, equalDOF constraints, - distributed loads, ground motions (`PathTimeSeries` / - `UniformExcitation`). -- **Materials and sections** — `Steel01`, `Steel02`, `Concrete01`, - `Concrete02`, `ElasticPP`, `Hysteretic`, fiber sections (rectangular / - circular patches + rebar layers), `SectionAggregator`, - `BeamWithHinges`. -- **Analyses** — static (load- or displacement-controlled), modal, - displacement-controlled pushover, transient time-history with - mode-1 Rayleigh damping. Chained workflows: gravity preload → - `loadConst -time 0.0` → pushover or transient. -- **Post-processing** — deformed shape (with scale slider), animated - mode shapes, axial / shear / moment diagrams, pushover curves - (in display units), time-history plots, hysteresis loops, - response-spectrum SRSS / CQC, snapshot + video export. -- **Persistence** — one JSON `.osmodel` per project, Pydantic-validated, - round-trips clean. -- **Examples** — 20+ verified examples, including OpenSees - Wiki Examples 1–4 and a fiber-section RC frame pushover. - See [`examples/README.md`](examples/README.md). +| Area | What you get | +| ---- | ------------ | +| **Modeling** | Grid wizards, nodes, frames (elastic + force-based), trusses, quads, zero-length sections, restraints, equalDOF constraints, distributed loads, ground motions (`PathTimeSeries` / `UniformExcitation`). | +| **Materials & sections** | `Steel01`, `Steel02`, `Concrete01`, `Concrete02`, `ElasticPP`, `Hysteretic`, fiber sections (rectangular / circular patches + rebar), `SectionAggregator`, `BeamWithHinges`. | +| **Analysis** | Static (load- or displacement-controlled), modal, pushover, transient time-history with mode-1 Rayleigh damping. Chained workflows: gravity preload → `loadConst -time 0.0` → pushover or transient. | +| **Post-processing** | Deformed shape with scale slider, animated mode shapes, axial / shear / moment diagrams, pushover curves, time-history plots, hysteresis loops, response-spectrum SRSS / CQC, snapshot + video export. | +| **Persistence** | One Pydantic-validated `.osmodel` JSON per project — diffs cleanly in Git, builds cleanly from Python. Analysis output in HDF5 (`*.osresults.h5`). | -## Tech stack +20+ verified examples ship with the repo, including OpenSees Wiki +Examples 1–4 and a fiber-section RC frame pushover. See +[`examples/README.md`](examples/README.md). -| Layer | Library | -| ------------ | ------------------------------------ | -| GUI | PySide6 (Qt 6) | -| 3D viewport | PyVista + pyvistaqt (VTK) | -| 2D plots | pyqtgraph | -| Solver | OpenSeesPy 3.8.0.0 | -| Numerics | NumPy | -| Storage | Pydantic v2 (model), h5py (results) | -| Tests | pytest, pytest-qt | -| Lint / type | ruff, mypy | - -## Architecture - -Strict MVVM + service layer. `core` is pure Python — no Qt, -no OpenSeesPy imports — and unit-tests in isolation. - -``` -views (Qt) → viewmodels → services (OpenSeesRunner, Persistence) → core (model) -``` - -Long version in [`docs/architecture.md`](docs/architecture.md), -including the OpenSeesPy command order the runner emits. - -## Install (development) - -**Desktop GUI** (Qt, PyVista, pyqtgraph, imageio): +## Quick start ```bash git clone ssh://git@smill-home.ddns.net/smill/otko.git @@ -94,26 +66,9 @@ python -m venv .venv .venv\Scripts\activate # Windows source .venv/bin/activate # Linux / macOS -pip install -e ".[gui,dev]" -``` +pip install -e ".[gui,dev]" # desktop: Qt + PyVista + dev tools +# pip install -e . # headless: core + services only -**Headless** (core + services only, no Qt): - -```bash -pip install -e . -``` - -That pulls pydantic, numpy, h5py, openseespy and nothing else. -Use it for scripts, notebooks, and web backends that reuse -`otko.core` or `otko.services` without the GUI. - -Python 3.10+. On Windows use **3.12+** — `openseespywin==3.8.0.0` -has no 3.11 wheel (`Requires-Python >=3.12`). Both pins already -live in `pyproject.toml`. - -## Quick start - -```bash python -m otko ``` @@ -121,15 +76,58 @@ Then: 1. **File → Open** → `examples/cantilever.osmodel`. 2. **Analyze → Cases** → run `Tip-Load`. -3. **Display → Show Force Diagram** → **M3**: linear moment, - 50 kN·m at the fixed end. **V2**: constant -10 kN. -4. **Display → Show Deformed Shape** → cantilever curve, as advertised. +3. **Display → Show Force Diagram** → **M3**: 50 kN·m at the fixed end. + **V2**: constant −10 kN. +4. **Display → Show Deformed Shape** → the cantilever curve. -Nonlinear version: open `examples/portal_pushover.osmodel`, -run `Push-X`, **Display → Show Pushover Curve**. Elastic ramp, -then a yield plateau as the base hinges form. +Nonlinear version: open `examples/portal_pushover.osmodel`, run +`Push-X`, **Display → Show Pushover Curve** — elastic ramp, then a +yield plateau as the base hinges form. -## Run the test suite +Python 3.10+. On Windows use **3.12+** — `openseespywin==3.8.0.0` +has no 3.11 wheel (`Requires-Python >=3.12`). Both pins already +live in `pyproject.toml`. + +## Architecture + +Strict MVVM + service layer, one direction only: + +``` +views (Qt) → viewmodels → services (OpenSeesRunner, Persistence) → core (model) +``` + +`core` is pure Python — no Qt, no OpenSeesPy imports — and unit-tests +in isolation. PySide6 + PyVista on the view, pyqtgraph for 2D plots, +Pydantic v2 for the model, h5py for results. Long version, including +the OpenSeesPy command order the runner emits, in +[`docs/architecture.md`](docs/architecture.md). + +## Roadmap + +[`docs/roadmap.md`](docs/roadmap.md) has the phase-by-phase plan. +Phases 0–7 (modeling, analysis, post-processing) are mostly done. +Phase 8 — isolators, ground-motion library, IDA, fiber-section +editor polish — is where the open work is. + +## Contributing + +Collaborators welcome — most useful to people who already work with +OpenSees and want a shorter path from idea to model: + +- **Structural / earthquake engineers** who can tell us when a feature + is almost right but not quite. +- **Researchers** running pushover, IDA, or response-spectrum studies + against hand-built scripts. +- **Python / Qt developers** into scientific desktop apps, VTK + rendering, or Pydantic schema design. +- **Students** learning FEM and GUI architecture — the examples and + tests are meant to read as documentation. +- **UX / icon designers** willing to argue about dialogs and toolbars. + +Bug reports and reproducible test cases count as contributions. Setup +and the rules enforced in review: [`CONTRIBUTING.md`](CONTRIBUTING.md). + +Test suite: ```bash pytest tests/unit # pure logic, milliseconds @@ -140,39 +138,10 @@ pytest tests/integration # real OpenSeesPy runs on bundled examples CI runs lint + the non-`slow` subset on Linux / macOS / Windows × Python 3.10 / 3.11 / 3.12. -## Roadmap - -[`docs/roadmap.md`](docs/roadmap.md) has the phase-by-phase plan. -Phases 0–7 (modeling, analysis, post-processing) are mostly done. -Phase 8 (isolators, ground-motion library, IDA, fiber-section -editor polish) is where the open work is. - -## Collaborators wanted - -Most useful to people who already work with OpenSees and want a -shorter path from idea to model — and would rather build it together -than alone. Open an issue or say hi if you are: - -- A **structural / earthquake engineer** who knows OpenSees Tcl - or OpenSeesPy and can tell us when a feature is almost right - but not quite. -- A **researcher** running pushover, IDA, or response-spectrum studies - who can check the GUI against hand-built scripts. -- A **Python / Qt developer** into scientific desktop apps, - VTK rendering, or Pydantic schema design. -- A **student** learning FEM and GUI architecture at the same time — - the examples and tests are meant to read as documentation. -- A **UX / icon designer** willing to argue about dialogs, toolbar - icons, and visual language. - -Bug reports and reproducible test cases count as contributions. -See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup and the rules -enforced in review. - ## License OTKO is **GNU Affero General Public License v3.0** -([`LICENSE`](LICENSE)). Read the license itself, not just this: +([`LICENSE`](LICENSE)). In short: - Research, education, personal projects: fine, keep the copyright notice. @@ -183,6 +152,6 @@ OTKO is **GNU Affero General Public License v3.0** modifications under AGPL-3.0. Commercial forks stay open. If you need a different arrangement -(e.g. closed-source commercial license), open an issue. +(e.g. a closed-source commercial license), open an issue. Copyright © 2026 Ozan and contributors. diff --git a/docs/logo.svg b/docs/logo.svg index 3b6f06f..2e3b844 100644 --- a/docs/logo.svg +++ b/docs/logo.svg @@ -5,41 +5,40 @@ - - + + - + - - - - - - - + + - - - - - - - - + + + + + + + + + + + + - + OTKO - + A SAP2000-STYLE GUI FOR OPENSEESPY diff --git a/snip3.png b/docs/screenshots/grid.png similarity index 100% rename from snip3.png rename to docs/screenshots/grid.png diff --git a/snip1.png b/docs/screenshots/menu.png similarity index 100% rename from snip1.png rename to docs/screenshots/menu.png diff --git a/snip2.png b/docs/screenshots/toolbar.png similarity index 100% rename from snip2.png rename to docs/screenshots/toolbar.png