Exchange data between applications
Two applications that share a project — a QGIS session and a Python script, say — can pass data back and forth without anyone watching for it. Each one keeps a small held folder that remembers which version of each item it holds. Three actions work from that folder:
- check tells you what is newer than what you hold, what is new, and what you can no longer see;
- get saves the latest version of an item and then holds it;
- send sends a file as a new item, or as the next version of an item you hold and wrote (or that a colleague wrote, when the project names you both as members who add versions to each other’s results).
Nothing changes in your folder until you get, and nothing changes in the project until you send. Every action ends in one sentence that says what happened. The command line also exits with a code: 0 done, 1 refused, 3 access, 4 not found or someone else was first, 5 try again.
Before you start
Section titled “Before you start”You need the SDK, a project access key, and configuration.json for the project (see
Build on Ophiolite). The examples read the key from
OPHIOLITE_ACCESS_KEY. To send, the key must be able to write. The examples name an item the
way you see it in the project, here “Picked points”; nobody copies an identifier.
ophiolite checkThe first check in a new folder only notes what you can see. After that it answers, for example,
1 newer: Porosity points, version 2 by Alice Example, 5 minutes ago. — or
Nothing is newer than what you hold. A check never saves anything but that note.
ophiolite get --name "Picked points" --output receivedThe folder received then holds the original file as it was sent, with data.json and
descriptor.json beside it, and the held folder remembers the version and the name you used:
Got Picked points, version 2 by Alice Example, 5 minutes ago. You now hold it; saved in /home/you/work/received. (the folder in full). Running it again says
You already hold the latest version of Picked points, saved in /home/you/work/received. If the item is
renamed later, the same command still finds it. When two items you can see have the same name, nothing is
saved and the answer lists them, for example More than one item you can see is called Top Rotliegend: a horizon by Ada (version 2) and a point set by Ben (version 1). Name the type as well. Add --type horizon.
Add --stay to keep the version you have: the first time it gets the latest, and later runs save nothing
new and say when there is a newer one: You stay on version 3 of Picked points. Version 5 is newer; get it with --latest to take it. One get with --latest takes the latest version, and from then on every get
does. Without either, the folder does what you last asked. A well log needs
the curves you want (--curve GR, repeated). A scalar map arrives as map.tif, a GeoTIFF
generated from the stored map — not the file that was imported — with source.txt and
manifest.json; its fingerprints are checked before anything is kept.
When a get is complete, the project’s Activity records that an application received that version. You see it under your access key’s name; other members of the project see “An application”, never the key. A get that stops before the files are saved records nothing.
PICKED=$(ophiolite get --name "Picked points" --output received --json | python3 -c 'import json, sys; print(json.load(sys.stdin)["technical"]["asset_id"])')ophiolite send porosity.csv --profile points-csv/1 --name "Porosity points" --how kriging --based-on "$PICKED"--based-on names the items you hold that your result is built from (one to 32). It takes the
item’s id, which the get’s --json answer carries (technical.asset_id), so the first line asks
for it rather than anyone copying it. The answer
is Sent Porosity points as a new item; it is private until you share it. To send the next
version of an item you wrote, add --of with its id, from the send’s own --json answer: Sent Porosity points as version 3. Version 2 is kept. State what the file says about itself with --declare, for example
--declare crs=EPSG:28992; what you do not declare stays unknown.
An item you uploaded takes its next version the same way. Add --rights-confirmed to confirm
that you may share this version, and name only that item with --based-on. Without the flag
nothing is sent: The project refused this: confirm that you may share this version with --rights-confirmed. Nothing was sent. The project compares the file and its declarations
with every version it has: if they are the same as one of them, nothing is sent and the
answer names that version.
When someone else was first
Section titled “When someone else was first”A send replaces only the version your folder holds. If a colleague — or your other application — added a newer version first, nothing is overwritten:
Version 3 was added by Alice Example, 2 minutes ago. Your change was not sent. Either get version 3 and look at it, or send yours as a new item.
There are two ways out, and both are yours to choose: get the newer version, look at it, and
send again with --of; or send yours without --of, as a new item beside it.
When a send is interrupted
Section titled “When a send is interrupted”The whole request is saved in the held folder before it is sent. If the connection drops, the
answer is Could not reach the project. Nothing was changed; for send, run the same command again: it will not publish twice. Run the same send again: it either finds the version that
arrived or sends it now, never both.
From Python
Section titled “From Python”The same three actions, with the same sentences, from a script:
held = client.exchange(".ophiolite-held")print(held.check().sentence)got = held.get(name="Picked points", output="received", stay=True)print(got.sentence)sent = held.send("porosity.csv", name="Porosity points", profile="points-csv/1", how="kriging", based_on=[got.technical["asset_id"]])print(sent.sentence)type="horizon" picks between items with the same name, as --type does. stay=True keeps the
version the folder holds and stay=False takes the latest, as --stay and --latest do; the
sentence then says stay=False where the command line says --latest.
held.fetch(..., stay=True) gives an application that places the data itself the version it holds, with
no output folder needed; confirm() on what it returns answers You stay on ….
A refusal raises an error whose sentence says what happened and what to do; outcome names it
for your code. There is no background watcher: a script that must react as things change calls
check() in its own loop, or keeps a full local copy as in
Keep in step with Workspace.
What each answer means
Section titled “What each answer means”| Answer | What to do |
|---|---|
| You stay on version … | Nothing new was saved. Get with --latest (stay=False) when you want the newer version. |
| More than one item you can see is called … | Add the type it names (--type, type=). |
| No item you can see is called … | Check the spelling, or ask whether the item is shared with you. |
| You can no longer see … | The item was removed or is no longer shared with you; ask its author. |
| This kind of item cannot be received by this script yet: … | Read it another way (part of a seismic volume, or its slices in Python), or name the curves of a well log. |
| The project did not allow this with this access key … | Use a key for this project that can write, or ask the item’s author. |
| You can only build on items you hold … | Get the item first. |
| Your access key is not accepted any more … | Ask for a new key. |
| Another program is using this folder … | Wait for it to finish; one folder per application. |
