Command line interface¶
The distribution is named ada-py, but the console script it installs is
ada — there is no ada-py command. Install the package with pixi,
then call ada:
In a pixi project (pixi add ada-py), run it through the project environment instead:
pixi run ada --help.
In a checkout of the adapy repository, pixi run ada ... runs the CLI from the
checked-out source (src/ on PYTHONPATH) rather than an installed release. It
defaults to the fem environment, the one pixi run test uses; pass -e
to run it in another environment that carries the prod feature, e.g.
pixi run -e tests ada view model.ifc.
The entry point lives in its own top-level package (ada_cli) so that
ada --help does not import the full CAD/FEM surface. Every subcommand
imports its implementation lazily, so an invocation only pays for what it uses.
One global option applies to all of them:
--log-level- Logging level for the commands that initialise the
adapackage (convert,view,results,audit repro,audit parity). DefaultINFO.
convert, view and results take --log-file PATH as well -- a per-command option
rather than a global one, because argparse only accepts the global ones before
the subcommand and ada convert in out --log-file run.log is how it gets
typed.
Every command exits 0 on success. An argparse error exits 2, and so does
a bare command with nothing to act on — a bare invocation prints that parser's
full help rather than a one-line usage, but to stderr, and still exits 2,
because a wrong invocation must not look like success to a script. An explicit
--help goes to stdout and exits 0.
Every command uses the same exit codes:
| Code | Meaning |
|---|---|
0 |
Success. |
1 |
The command line was fine, but the operation failed or was refused: an HTTP error, a declined request, an aborted prompt, a tool missing from the environment, an uncaught exception. |
2 |
The command line was wrong: an argparse error, a bare invocation, or a missing or invalid argument, including a missing URL, token or scope. Printed as ada <command>: error: <what was wrong> where the command raises it itself. |
3 |
convert --strict found an omission or a suspect finding. |
To choose between 1 and 2: if changing the command line would fix it, it is 2.
The command groups are convert, view, results, build, files, audit,
serve, desktop and viewers. The first three run entirely locally; the rest of this page notes
where a group talks to a hosted viewer instead.
ada convert¶
Convert a model to another format. Both ends are inferred from the file
extensions, and --from / --to override that inference.
Read (--from) |
Extensions | Notes |
|---|---|---|
ifc |
.ifc |
|
step |
.step, .stp |
|
xml |
.xml |
GeniE XML. |
gnx |
.gnx |
GeniE workspace: the same concept XML zipped with its ACIS body, which is what GeniE opens directly. ada.from_gnx is the Python entry point. A body GeniE V9.3 saved in binary (acisGeometry.sab) reads as its text twin would; one holding a record the reader was not verified on is refused by name. |
acis |
.sat, .acis |
|
abaqus |
.inp |
Also how you read a Calculix deck; they share the keyword syntax. |
sesam |
.fem, .sif |
|
code_aster |
.med, .rmed |
Write (--to) |
Extensions | Notes |
|---|---|---|
ifc |
.ifc |
|
step |
.step, .stp |
|
gltf |
.gltf, .glb |
.glb is the binary flavour. |
xml |
.xml |
GeniE XML. |
gnx |
.gnx |
GeniE workspace. Same model as xml, in the container GeniE saves and opens; Assembly.to_gnx is the Python entry point. The ACIS body is text unless --binary-acis asks for binary. |
abaqus |
.inp |
Default owner of .inp. One self-contained deck — the include files the writer uses internally are inlined and removed. |
calculix |
.inp |
Shares .inp with Abaqus, so it is reachable only as --to calculix. |
sesam |
.fem |
Default owner of .fem. The .FEM deck alone; --sestra-inp adds a sestra.inp made from the model's analysis step. |
usfos |
.fem |
Shares .fem with Sesam, so it is reachable only as --to usfos. |
code_aster |
.med |
The output is the .med mesh; the .comm command file and two .json maps land beside it. |
opencourant |
.rad |
OpenCourant (OpenRadioss) starter deck <name>_0000.rad. The engine deck <name>_0001.rad is written beside it when the model carries an explicit step. Shell models only for now. |
Two extensions name more than one FEM format — .inp is both Abaqus and
Calculix, .fem is both Sesam and USFOS — so each has exactly one default
owner, picked to agree with what ada.from_fem already infers from a path:
.inp means Abaqus, .fem means Sesam. The minority dialect is reached with
--to and no other way. Inference is not silent about it: resolving a shared
extension is logged at INFO, naming the flag that would have chosen the other
one.
xml and gnx are the inverse case: one model, two containers. A .gnx is
the GeniE workspace -- the concept XML plus its ACIS body, zipped the way GeniE
saves one -- so the extension decides which container is written and --to
cannot override it. ada convert in.xml out.gnx --to xml is a usage error
rather than an override, because the flag selects no conversion there: it can only
put plain XML under a name GeniE will try to unzip, or a zip under a name an XML
parser will try to parse, and neither file opens. Drop the flag and let the
extension pick, or name the output with the extension you meant.
The output argument always names one file, never a directory, and that exact
path is what exists when the command exits 0. This is worth stating because
the FEM writers do not work that way on their own: called through the Python API
they name the deck after the model and leave it in a scratch directory
(<scratch>/<name>/<name>T1.FEM for Sesam, ufo_bulk.fem for USFOS
regardless of the name given). The CLI writes into a temporary directory next to
your output and moves the format's primary deck onto the path you asked for.
Formats that genuinely need more than one file write the rest beside it, under the writer's own names — so point the output at a directory of its own when the sidecars matter. Every path written is printed to stdout as an absolute path, one per line, the file you asked for first and the sidecars after it:
$ cd /work && ada convert model.inp analysis/mesh.med
/work/analysis/mesh.med
/work/analysis/mesh.adapy_fem.json
/work/analysis/mesh.comm
/work/analysis/mesh.name_map.json
The sidecars are printed sorted by name, so the output is stable between runs. The temporary directory the deck is built in goes away even if the writer fails, so a failed conversion does not litter the output directory; in the rare case it cannot be removed, a warning names it.
Sidecars keep the writer's own names, so converting twice into one directory replaces the previous run's sidecars -- that is warned about, and giving each conversion its own output directory avoids the question entirely.
Two consequences of that rule are worth knowing. A Sesam output may be named
either model.FEM or modelT1.FEM — the T1 the Sesam writer appends is
recognised, not doubled, so a name that already has it needs no rename
afterwards. And Code_Aster output must be named *.med, because the mesh is
the primary file; naming the .comm is a usage error rather than a silent
surprise.
ada convert model.sat model.stp
ada convert model.ifc model.glb
ada convert model.gnx model.ifc # GeniE workspace -> IFC
ada convert model.xml model.gnx # concept XML -> workspace
ada convert model.xml model.gnx --binary-acis # same, ACIS body as binary SAB (GeniE V9.3+)
ada convert model.inp model.FEM # Abaqus deck -> Sesam deck
ada convert model.inp analysis/modelT1.FEM # same, named as Sesam names it
ada convert model.inp ufo/model.fem --to usfos
ada convert model.FEM ccx/model.inp --to calculix
ada convert deck.dat model.FEM --from abaqus
ada convert --list-formats
-f,--from- Read the input as this format instead of inferring it from the extension.
Use it for an Abaqus deck that is not named
.inp, or to read a Calculix deck (--from abaqus). There is deliberately no--from calculix: adapy has no Calculix reader, and a.frdis a result file, not a model. -t,--to- Write this format instead of inferring it from the output extension. This is
the only route to
calculixandusfos. An explicit--toalways wins; if it disagrees with the extension you named, the conversion still runs and logs a warning naming the usual extension. --list-formats- Print both tables, with the primary file each FEM writer produces, and exit
0. Works without the input and output arguments. --split- Split ACIS/SAT bodies into individual faces.
--limit- Stop after this many geometries. Debugging aid; unset by default.
--log-file [PATH]- Write adapy's log records to this file, truncating it first, and leave only
warnings and errors on the console. Given without a path,
convertwrites<OUT stem>.logbeside OUT (put the flag after the positionals, or it takes the input file for its path). Useful on large FEM decks, where theINFOstream is worth keeping but not worth reading as it scrolls past. Without the flag nothing changes: every record at--log-levelgoes to stderr. --superelement- The Sesam super element number, written as the deck's
IDENTSELTYPand used to name the file<prefix>T<N>.FEM. Without it theT<N>in OUT decides, then what the input says (a.SIN's superelement, a.FEM'sIDENT SELTYP), then anR<N>/T<N>in the input's name, then 1. --super-element- Sesam
.SINonly. Converts just this superelement (type number12, type and instance12.1, or Xtract's labelSEL12.IND1), written to OUT as given. Repeat it to convert several, each to<OUT stem>T<N><OUT suffix>. Without it, a.SINholding an assembly is written as one such file per first-level superelement with a mesh, each with its ownSELTYP, and every file written is printed. --merge- Sesam
.SINassembly only. Writes all first-level superelements as one file at OUT, with the top level'sSELTYP. Each superelement is placed by its translation and its node and element numbers are prefixed by its type number (type x 10^6 + its own number), so they stay unique. A superelement placed with a rotation is refused, since the beam orientations and local systems would have to be turned with it. Cannot be combined with--super-element.
Without it the T-number in the output name decides, so myPrefixT10.FEM
is super element 10. With neither, it is 1 -- and the run says so, rather than
leaving you to discover it from Presel. Sesam expects the number in the deck and
the number in the file name to agree, because Presel matches them when it
assembles, so a flag contradicting the name is a usage error rather than a
silent override.
--sestra-inp- For
sesamoutput: also write a Sestra control file,sestra.inp, beside the deck. adapy makes it from the model's first step (a linear static or eigenvalue analysis) and points it at the super element written (ITOP). It is not read from the input -- not even from a.SIN. By default only the.FEMis written. Any other output format refuses the flag. --binary-acis- For
gnxoutput: store the ACIS body as binary SAB (acisGeometry.sab), the way GeniE V9.3 saves a workspace with Write ACIS files in binary format on, and set that option in the workspace so a re-save in GeniE stays binary (Assembly.to_gnx(..., binary_acis=True)in Python). The default is text, because GeniE before V9.3 opens a binary workspace as an empty model without a message; V9.3 reads either. Any other output format refuses the flag. --strict- Exit
3if anything in the input could not be written to the output, or if the input itself looks wrong. Approximations on their own do not fail -- a tie resolved to the nearest node is always one. The deck and the conversion report are written either way;--strictreports, it does not withhold.
What a conversion could not carry across¶
Every format lacks something another can say, so a conversion can be complete,
approximate, or incomplete. ada convert says which, in three places:
- a short summary on stderr at the end -- the status, then one line per
finding. It is printed rather than logged, so
--log-filecannot hide it, and it is on stderr soada convert in out > paths.txtstill captures nothing but paths; <OUT stem>_conversion_report.jsonbeside the output, listing every finding with counts and measurements, and named among the written paths on stdout. It is written only when there is something to report: a clean conversion leaves the output file alone;- the exit code, under
--strict.
A finding is one of four kinds. omitted means the construct produced nothing
in the output -- an unsupported constraint type, a keyword the reader has no
handler for. suspect means the output is faithful and valid but the input
looks like a modelling error, so the result is faithful to a wrong model: two
constraints making one node's degree of freedom dependent is the case it exists
for, because Sesam sums linear dependencies and would quietly add them together.
approximated means something was written with different physics, and carries a
measure of the difference (a pairing distance, a dropped weight). note means
it was written faithfully and is worth a human's attention, or is plain inventory.
Omissions and suspect input fail --strict; approximations and notes do not.
Findings are counted per construct, not per node: a deck that drops ten thousand springs reports one line saying ten thousand, because a log nobody can scroll hides an omission just as well as no log at all.
ada view¶
Open the built-in web viewer on a model or a result file.
A result file is recognised by its extension and shown with its results, every
field and step selectable in the viewer, as ada.from_fem_res(path).show()
would:
| Results | Extensions |
|---|---|
sesam |
.sin, .sif |
abaqus |
.odb (needs a local Abaqus to export it) |
calculix |
.frd |
code_aster |
.rmed |
opencourant |
.radanim |
ada view model.ifc
ada view model.ifc --renderer trimesh
ada view deck.dat --from abaqus
ada view run.SIN # the results
ada view run.SIN --super-element SEL12.IND1 # one superelement of the assembly
ada view run.rmed --from code_aster # the mesh alone
-f,--from- Read the input as this model format instead of inferring it from the
extension. Same names as
ada convert's--from. On a result file it reads the mesh alone, without the results. --rendererreact(default) ortrimesh. Results are shown withreact.--host- Host to bind the viewer websocket to. Default
localhost. --ws-port- Websocket port. Default
8765. --split,--limit,--log-file- As for
ada convert. --super-element- Sesam
.SINonly. A superelement assembly is read whole by default, every superelement placed and merged; this reads one superelement instead, given as a type number (12), type and instance (12.1) or Xtract's label (SEL12.IND1). Repeat the flag to read several, merged like the whole assembly. --stats- Result files only: print the overview
ada results statsprints before showing the result. --viewer- Open an installed viewer bundle instead of the built-in viewer (see
ada viewers). Default:$ADA_VIEWER_BUNDLE, else the built-in viewer.
ada results¶
Read FEA result files -- the extensions ada view shows as results -- without
opening a model. Both subcommands take --super-element and --log-file
as ada view does.
ada results stats- Print an overview of one result file: the software, the steps with their names, the mesh contents and one row per field (kind, steps, components, shape).
ada results compare- Compare
OTHERagainstBASE, two runs of the same model with different loads or boundary conditions, and print the fields that differ, worst first. Then show the differenceOTHER - BASEin the viewer: one field per compared field, for every load case and combination, each coloured on a scale centred on zero, so a model compared with itself is one colour. The two must share a mesh -- node and element ids, coordinates and connectivity -- or the command exits2;--no-check-meshcompares anyway.--fieldslimits it to the named fields,--rtolsets the relative difference above which a field counts as differing (default1e-5),--max-rowscaps the table (default 50,0for all), and--no-showstops after printing.--renderer(react),--hostand--ws-portare as forada view.
ada results stats run.SIN
ada results compare base.SIN other.SIN
ada results compare base.SIN other.SIN --fields sesam.nodes.displacement --no-show
ada build¶
Run the entrypoints declared in an ada_config.toml and push the artefacts
they produce to a viewer. The three subcommands share --config (default
ada_config.toml), --entrypoint (run only the named one) and
--output-dir (default .ada-build).
ada build run- Run the entrypoints and stage the artefacts locally.
ada build upload- Upload the artefacts already under the output dir.
ada build run-and-upload- Chain the two. This is the one to use in CI.
Uploading needs a target and a credential, read from ADAPY_VIEWER_URL and
ADAPY_VIEWER_TOKEN (the newer ADAPY_API_BASE / ADAPY_API_TOKEN pair
is accepted too, and wins when both are set). A .env in the working
directory is picked up automatically; real environment variables win over it.
ada files¶
List and move blobs in a viewer scope. Every subcommand takes --url,
--token and --scope, each defaulting to the matching environment
variable. A scope looks like project:my-slug or user:me.
ada files list- List keys in the scope.
--prefixfilters,-l/--longadds sizes. ada files download- Download
KEYtoDEST(default: its basename in the working directory). Goes S3-direct through a presigned URL where the backend supports it;--via-apiforces the tunneled GET instead. ada files upload- Upload
SRCtoKEY(default: the basename ofSRC).--via-apiforces the tunneled PUT, which is subject to the direct-upload size cap. ada files delete- Delete the given keys, and/or everything under
--prefix.-y/--yesskips the confirmation prompt.
ada files list --scope project:my-slug -l
ada files upload model.glb versions/main/abc1234/model.glb
ada files delete --prefix debug/ --yes
ada audit¶
A read-only client over the viewer's audit API, plus two local re-run paths.
Credentials come from ADAPY_API_TOKEN with the base URL from
ADAPY_API_BASE or ADAPY_BASE_URL; a bare host is accepted and gets
https:// prepended. Every subcommand accepts --url, --token and
--json (raw JSON instead of a table).
ada audit runs- List recent regression-sweep runs.
--limit(default 20) and--beforepage through them. ada audit run- Show one run's per-cell jobs.
--failednarrows to failures,--formatto a single target format. ada audit log- Query the per-conversion audit log, filtered by
--source,--target,--status,--keyor--grep, and server-side by--action(convert,view,render,validate, …) and--since/--until(a relative duration such as6hor an ISO-8601 instant). ada audit loads- Per-load browser model-load metrics recorded by the viewer's opt-in
instrumentation: transport, TTFB, download, parse, prepare and first-render
times, bytes and triangles. Filter with
--since,--until,--keyand--device(a device-id prefix);--kind renderlists steady-state render windows instead. A row is written only once a load completes;transport=relayedmeans the server relayed the bytes instead of a direct storage fetch, with the reason inclient_metrics.fallback_reason; andfirst_render_mspauses while the tab is hidden. ada audit loads-summary- Per-file p50/p95 load times over
--since-days(default 1), split into network, CPU and GPU time with the dominant bottleneck.--kind rendersummarizes render windows (FPS, frame and GPU time). ada audit loads-hotspots- Function-level self-time across profiled browser loads (or render windows
with
--kind render), optionally for one--key. ada audit perf- Hot paths across conversions — function-level by default, cell-level when
--run,--worker-tagor--triggeris given. ada audit profile- Function stats for a single audit row's cProfile.
--sorttakescumtime(default),tottimeorncalls. ada audit fetch- Download one conversion's source blob under
--out(default./audit_repro). ada audit logfile- Download a conversion's captured stdout/stderr. Prints to stdout unless
--outnames a file. ada audit repro- Fetch a conversion's source and run it locally, optionally against a
different
--targetformat. ada audit wasm-sweep- Re-run a remote run's cells locally through the in-browser WASM engine (node-pyodide) and write a pass/fail report. Writes nothing back to the database.
ada audit parity- Cross-format visual-parity check on a local model: export to each of
--formats(defaultifc,xml,step), reload, and compare the visualized element counts.
ada audit runs --limit 5
ada audit run 42 --failed
ada audit repro 1234 --target step
ada audit loads --since 2h --device 3f2a9c1e
ada audit loads-summary --since-days 7
ada serve¶
Run one of the long-lived server processes. Both are configured through the
environment; api also takes --viewer, --max-jobs and --cpu-budget.
ada serve api- Run the REST API under uvicorn.
--viewer NAMEserves an installed viewer bundle instead of the built-in viewer (seeada viewers); an explicitADA_VIEWER_STATIC_PATHstill wins. --max-jobs N/--cpu-budget CORES- Only without a job queue (
ADA_VIEWER_NATS_URLunset), where the API runs every job itself: how many jobs run at once (1-256; the rest wait in order), and the CPU the running jobs share, as cores (4), a fraction (0.5) or a percentage (50%). They setADA_LOCAL_JOB_PROCESSES/ADA_LOCAL_JOB_CPU_BUDGET, win over the value saved under Settings > Local jobs, and are saved. Unset: the saved value, else half the cores (at most 4) and every core. A value out of range is a usage error (exit 2). ada serve worker- Run the conversion worker (a NATS JetStream consumer).
ada desktop¶
Run the local viewer and open it in a native window instead of a browser tab.
It starts python -m ada.comms.rest with local storage, no login and no job
queue, bound to 127.0.0.1, opens the ada-desktop window on it, and stops it
when the last window closes. Pop-outs and dashboard windows open as native
windows. The window shell (ada-desktop) comes in a separate conda package,
ada-py-desktop (Windows only for now);
see src/desktop/README.md in the repository for how it is built and what it
allows the page to do.
ada desktop # the viewer, empty
ada desktop model.ifc # upload model.ifc into the personal scope and open it
ada desktop --no-window # the viewer only; open the printed URL in a browser
FILE- Optional. Uploaded into the local viewer's personal scope under its file
name and opened with
?file=, as if uploaded from the page. A type the viewer cannot read is reported and the window opens without it. --port N- The viewer port. Default:
$ADA_DESKTOP_PORT, else a fixed port for the current user in 38500-38999 (ada desktop --helpshows yours). It is fixed on purpose: the viewer keeps layouts and settings in browser storage, which belongs to the page's origin and so to the port. If another program holds the port, this launch uses a free one and warns that it starts without those settings. If a viewer started by anotherada desktopalready runs there, the command opens one more window on it instead, and that viewer stops only when every window is closed. --data DIR- Local storage (uploaded files, derived results). Default: a per-user
directory,
%LOCALAPPDATA%\ada\desktop\dataon Windows. --viewer NAME- Serve an installed viewer bundle (see
ada viewers) instead of the built-in viewer. --max-jobs N/--cpu-budget CORES- The local viewer's job limits, as for
ada serve api. --static DIR/--zip FILE- Serve a built viewer directory, or a single-file viewer zip. The default is the zip shipped in ada-py, unpacked once per content hash into the user cache directory.
--binary PATH- The
ada-desktopshell. Default:$ADA_DESKTOP_BINARY, elseada-desktoponPATHor in the active environment (Library\binon Windows). Without one the command says how to install it. --title T- Main window title (default: Ada Studio).
--no-window- Start the viewer only, print its URL and wait for Ctrl+C.
--shell-arg ARG- Pass
ARGto the shell, e.g.--shell-arg=--no-spacemouse. Repeatable. --timing- Print how long the viewer took to start and stop.
--dev- For working on adapy itself (a source checkout, Windows only for now;
pixi run desktopdoes this and builds what it needs). The viewer runs underuvicorn --reload(Python edits undersrc/adarestart it), the frontend runs under Vite with hot module reload, and the window opens on Vite, which proxies/api,/config.jsand/healthzto the viewer. The shell is not reloaded. Vite listens on the viewer port + 500 unless--dev-port Nsays otherwise. --frontend-url URL- Implies
--dev, but opens an already running Vite dev server (loopbackhttponly) instead of starting one. Start it withADA_DESKTOP_BACKEND=http://127.0.0.1:PORT/and--config vite.config.desktop.ts.
Connecting to a hosted server¶
ada desktop can open a hosted (for example on-premise) deployment instead of
the local viewer, to use its storage, conversions, jobs and sign-in. No local
viewer is started; the window loads the server's own URL, so the page runs on
the server's origin and its normal sign-in works unchanged.
ada desktop --server https://studio.example.com
ada desktop servers add work https://studio.example.com
ada desktop --server work
ada desktop servers list
ada desktop servers remove work
--server URL|NAME- The deployment to open: an
httpsURL, or the name of a saved server. Default:$ADA_DESKTOP_SERVER. The origin the window will trust is printed first.FILEand the local-viewer flags (--port,--data,--static,--zip,--viewer,--max-jobs,--cpu-budget) cannot be combined with it. With--devit means--backend. --local- Start the local viewer even though
$ADA_DESKTOP_SERVERis set. --insecure- Accept plain
httpfor a server on a non-loopback host (lab setups only; sign-in tokens then cross the network unencrypted). https is required otherwise. --auth-origin ORIGIN- An extra identity-provider origin the window may sign in at. The provider
the server advertises (
/api/config) is allowed automatically; add the others a federated sign-in passes through. Repeatable;servers addsaves them with the profile. servers list | add NAME URL | remove NAME- Manage saved servers, kept in
%APPDATA%\ada\desktop\servers.jsonon Windows ($XDG_CONFIG_HOME/ada/desktop/servers.jsonon Linux). --backend URL|NAME- Implies
--dev, against a hosted server (a URL or a saved name) instead of a local viewer (source checkout, Windows;pixi run desktop-backend NAME). Vite serves the local frontend with hot reload onhttp://localhost:PORT(the--devport, viewer port + 500, fixed per user;--dev-port Noverrides) and proxies/api(websockets included),/config.jsand/healthzto the server. The command printsRegister this redirect URI for the app's SPA platform: http://localhost:PORT/auth/callback; register it once in the server's identity provider.--dev --server NAMEis the same; a plain--devstays local.pixi run desktop-server NAMEjust opens the server.
See src/desktop/README.md for the security model (which origins may be shown
and which one is granted native events) and the sign-in details.
ada dev¶
Develop against the studio, with what you edit reloaded live.
ada dev connections- Develop a connection library: the joint details registered with
@register_connection. Starts the local viewer (asada desktopdoes) with the library in--dirloaded and opens the studio's connection builder. Pick a spec from the library, then edit each member: a beam's section, a plate's thickness and extent, the angle between them. The joint is rebuilt on every change, and again on every saved edit to the library's files. A builder that raises, or a module that does not import, shows its traceback in the builder until the next save fixes it. ada dev joints- The same as
ada dev connections.
The library declares itself in ada_connections.toml in --dir (default
.):
[library]
name = "my-connections" # shown in the studio (default: the folder name)
package = "my_project.connections" # imported, with every submodule, to register the specs
# loader = "loader.py:load_all" # ...or a function that does the importing itself
watch = ["."] # what a saved change reloads (default: this folder)
python_path = ["../.."] # prepended to sys.path, for a library that is not installed
# handler_kwargs = "dev.py:preview_kwargs" # a function returning extra keyword arguments for the builders
Paths are relative to the toml. The library runs in a process of its own
next to the viewer. A reload drops the library's own modules and specs and
imports them again, so the heavy imports stay loaded and a reload takes well
under a second; editing ada_connections.toml starts a fresh process. The
preview members come from the spec's roles: a landing beam runs along X
through the joint, an incoming beam starts there at the role's angle, and a
plate stands on the landing member's top face. A spec's defaults fill the
form; fields the spec leaves out take a representative value.
Options: --port N (default: your ada desktop port + 1000, so the two run
side by side), --data DIR, --static DIR / --zip FILE / --viewer NAME
(the viewer build to serve, as for ada desktop), --browser (open the
default browser rather than the ada-desktop window, which is also the
fallback when the shell is not installed), --no-window, --binary PATH,
--title, and --dev (run the viewer from the source checkout with
hot reload, as ada desktop --dev).
With welds, the detail can be simulated: the Connection tab's Simulate...
button offers it as a weld assembly subject and opens the Simulations panel,
where the providers that accept one can run on it. The studio has no simulation
workers of its own, so point it at an Ada Studio that has them with
--sim-remote URL (and --sim-token TOKEN, or ADA_SIMULATION_REMOTE_TOKEN;
--sim-scope SCOPE for the remote scope the run lives in, default user:me):
the remote's providers are listed beside the local ones, and a run on one
uploads its files to the remote, starts there, and is followed from here (the
replay, live view and console read it through this studio).
ada dev connections --dir path/to/my_project/connections
ada dev connections --dir path/to/connections --sim-remote https://studio.example.com --sim-token $TOKEN
ada viewers¶
List the installed viewer bundles. adapy's own viewer carries no plugins; they join its frontend at build time. A package that ships plugins can build the viewer with them and install the result as a bundle, so a local viewer can use it without building anything:
<prefix>/share/ada/viewers/<name>/
bundle.json name, title, adapy_version, plugins, default_ui
dist/ the hosted build, served by `ada serve api`
index.zip optional: the single-file build `ada view` and show() open
--viewer NAME on ada view and ada serve api (or ADA_VIEWER_BUNDLE=NAME)
picks one; unset, or builtin, is the built-in viewer. ADA_VIEWER_BUNDLE_PATH
adds directories to look in. An unknown name is an error naming what is
installed.
ada viewer¶
Drive your open viewer -- focus a clash joint, select, move the camera, load a detail model -- and read what the clash pipeline stored. See the viewer control API for what each command does in the viewer.
Where it goes. --via auto (the default) uses a hosted viewer's REST API when a viewer URL
is configured (--url, or ADAPY_API_BASE / ADAPY_BASE_URL / ADAPY_VIEWER_URL, with the
token from --token / ADAPY_API_TOKEN), and otherwise the desktop viewer's websocket server
(--ws-host, --ws-port; default localhost:8765, what ada view starts). --via remote or
--via local forces one. A hosted server must allow it (ADA_VIEWER_CONTROL), and a tab takes
part only with its External controls switch on.
Every command takes --json for the raw answer instead of a summary. Those that drive a tab take
--session (one tab; locally a viewer's instance id; default every tab) and --wait (seconds to
wait for the answers, default 10). Exit code 1 when the server refuses (no viewer open, viewer
control disabled -- its message is printed) or any tab answers an error, has closed or did not
answer in time.
ada viewer sessions- List your open viewer tabs.
ada viewer state- What each tab shows: scope, loaded and detail models, selection, camera, clash run and joint.
ada viewer focus-joint- Focus a clash joint (
JOINT_ID): select its members and frame them.--run-keyopens that convex-contact run first;--no-frameleaves the camera. ada viewer select- Select objects by name (
NAMES...) and frame them;--filenames the loaded model. ada viewer clear-selection- Clear the selection.
ada viewer camera- One of
--fit selection|all,--view top|bottom|front|back|left|right|isometric,--eye x,y,z --target x,y,z,--box xmin,ymin,zmin,xmax,ymax,zmax. ada viewer open-detail- Load a detail model (
DETAIL_ID);--jointshows that joint in it, or in the run it was made from when it was not built.--with-sourcealso loads the saved group its run was made on, so the welds sit in their structure. ada viewer load-group- Load a saved group into the scene by name (case-insensitive) or id, as the Scene panel's "Load
into scene" does.
--idtakes the argument as an id;--selectkeeps its members selected,--framefits the camera to them. ada viewer find- Look objects up by name: which model, how many, centre and box. Changes nothing.
ada viewer run- Send a command or a batch from a JSON file (
-for stdin): one command, a list of commands (run in order, stopping at the first that fails), or aPOST /api/viewer/commandsbody. ada viewer schema- The command vocabulary as JSON schema.
ada viewer joints- A clash run's joints (hosted only): members with their roles, centre, applicable specs.
--runa run key orlatest(default),--ids,--member,--limit,--scope. ada viewer groups- The scope's saved groups (hosted only): id, name, how many members, which models.
--namenarrows it. ada viewer detail- A detail model per joint (hosted only): built (connections, welds with type, throat and
length), declined or failed and why, failed welds, and a joint's members from its run.
--jointsnarrows it.
ada viewer sessions
ada viewer focus-joint 0123456789ab --run-key _clash/0000/run.json
ada viewer camera --view isometric
ada viewer load-group "Frame A" --frame
ada viewer open-detail 20260101T120000000Z-0123abcd --joint 0123456789ab --with-source
echo '[{"action": "open_detail_model", "detail_id": "20260101T120000000Z-0123abcd"},
{"action": "focus_joint", "joint_id": "0123456789ab"}]' | ada viewer run -
ada viewer detail 20260101T120000000Z-0123abcd --joints 0123456789ab