models, collections, and the `fetch_*` helpers). This page describes how Sonador applies them and the
"rules of thumb" that govern the Sonador IO client specifically.
* Sonador client libraries provide an object relational map (ORM) interface to interact with system resources stored within Sonador and Orthanc.
- The [Sonador IO Client](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-client) libary (which is a core dependency of all other Sonador libraries) inherits from the [Guru Client](https://code.oak-tree.tech/guru-labs/guru-client), which provides base utilities and core object clases.
...
...
@@ -25,13 +36,54 @@ The Guru Client provides three base components:
* collection classes which can be used to interact with logically grouped sets of models
TODO:Describe server implementation
#### Servers
Sonador IO provides two server classes, both derived from the Guru Client `RemoteServer`:
TODO:Describe base model class and primary interface
***`sonador.servers.SonadorServer`** — the connection to a Sonador web application. It handles
authentication (an API access token sent as the `api-token` header, an OAuth `Bearer` token, or an
HMAC-SHA1 signed URL built from an access-id/secret-key pair), exposes administrative resources
(users, groups, credentials, tokens), and is the entry point for retrieving imaging servers via
`get_imageserver` / `fetch_imageservers`.
***`sonador.servers.SonadorImagingServer`** — a handle to a specific Orthanc-backed PACS that is
registered with the Sonador app. It is itself a Sonador resource (fetched from
`/visionaire/api/pacs`) and provides the query, retrieval, upload, and bulk-operation methods used
to work with imaging data. Requests to Orthanc are authenticated and routed through Sonador, so
ACLs are enforced.
TODO:Describe base collection model class and primary interface
A server is most often built from environment variables with `sonador.helpers.initenv_sonador_server`
`SONADOR_VERIFY_SSL`), which is the same configuration surface exposed by the command-line tools.
TODO:Describe REST-like rules of thumb for Sonador applications.
#### Base model class
Imaging models inherit (through `SonadorBaseObject`) the Guru Client model interface and add the
Sonador conventions:
***`fetch_endpoint`** — the management endpoint for the resource type (e.g. `patients`, `studies`,
`series`). Scheme/host/port come from the server.
***`pk_attr`** / **`pk`** — selects the JSON field that uniquely identifies the instance (Orthanc
resources use `ID`); `resource_url` is derived from the endpoint and the `pk`.
***`update(odata)`** — `PUT` changed attributes (the REST/details endpoint).
***`delete()`** — `DELETE` the instance from the server.
Resource models additionally expose **navigation properties and `fetch_*` methods** that return child
collections (a study's series, a series' instances), and metadata helpers (`fetch_meta`,
`fetch_attachments`, ACL accessors). Many of these are cached on first access.
#### Base collection class
Collections inherit the Guru Client `JsonObjectCollection`/pagination behavior and add the
management-endpoint conventions as class methods:
***`fetch(...)`** — retrieve a set of models (with pagination and filtering).
***`fetch_modelinstance(objectid, ...)`** — retrieve one model by identifier.
***`create(odata, ...)`** — `POST` a new instance.
Child collections that belong to a parent (for example `DcmSRSeriesCollection` under a study, or
`ResourceCommentCollection` under any resource) take the parent as an argument and thread it through
`_init_collection_models` so that each model can build its own URLs and reach the imaging server
(`parent.pacs`). The Sonador IO client also provides `SonadorCachedObjectCollectionMixin`, which keeps
an in-memory hashmap of models keyed by `pk` for rapid `get_modelinstance(pk)` lookup.
#### REST-like rules of thumb for Sonador applications
* By convention, every Guru, Oak-Tree, and Sonador API resource is associated with **two primary endpoints**.
-**A "management" endpoint** that is used for describing the resource, retrieving collections of logically grouped models, and creating new instances of the model.
...
...
@@ -45,7 +97,7 @@ TODO:Describe REST-like rules of thumb for Sonador applications.
+`DELETE`: remove the model instance
* Client design philosophies
- Client model classes contain the properties that define what the model "is" and where its data resides.
- Client collection classes read model properties to execute
- Client collection classes read model properties to execute requests against the management endpoint on the model's behalf.
- Client model and collection operations are organized around the capabilities of the endpoints they interact with.
dcm,_changed=dcm_part10_backfill(dcm)# ensures valid Part-10 file meta
# `dcm` is now safe to upload via SonadorImagingServer.upload_image(...)
```
The `remote` module includes models (sometimes called data objects)
**2. In-memory model collections.**`sonador.local` provides `SonadorLocalObject` and
`SonadorLocalCollection` (built on the Guru Client `local` base classes). They present the same model
interface as remote resources but hold data the application has assembled itself. The
`SonadorCachedObjectCollectionMixin` they use indexes models by `pk` so that `get_modelinstance(pk)`,
`append`, and `extend` stay fast for large sets. Use `local` when you need DICOM in the Sonador object
model before (or without) a round-trip to a server — bulk-prepping files for upload, or caching
results client-side.
Model class properties.
*`fetch_endpoint` (`str` or `property` which returns `str`): defines the "management" interface for the dataclass. _The endpoint should contain the resource path, query parameters and fragments. Schema, network location, and port will be taken from the server._
> 📘 The data-preparation tasks in `sonador.tasks` (uploads, reindexing) build on these helpers.
### `remote`
The `remote` axis is the heart of day-to-day use: models and collections backed by the Sonador and
Orthanc server APIs. A model (sometimes called a *data object*) maps a server resource to a Python
object whose properties expose its DICOM tags and whose methods expose the operations the server
supports.
Model class properties:
***`fetch_endpoint`** (`str`, or a `property` returning `str`): defines the "management" interface
for the dataclass. _The endpoint should contain the resource path, query parameters, and fragments.
Scheme, network location, and port are taken from the server._
***`pk_attr`** / **`pk`**: identifies the resource; Orthanc resources key on `ID`.
***`resource_url`**: the details (REST) endpoint for the instance, derived from `fetch_endpoint` and
the `pk`.
The imaging resource hierarchy mirrors DICOM and is reachable by navigation:
