QingYuan Simulator API

Based on the functional-structural plant model GreenLab, the cPlant team developed two software packages, 'GreenScilab' and 'QingYuan'. QingYuan can simulate trees such as albizia, ginkgo, pine and orange. An online simulation API is provided by this site.

1. Obtain a token

Exchange your username and password for access / refresh tokens:

POST /api/token/pair

{
    "username": "your_username",
    "password": "your_password"
}

Response:

{
    "username": "your_username",
    "access": "<access token>",
    "refresh": "<refresh token>"
}

2. Refreshing and verifying a token

POST /api/token/refresh

{
    "refresh": "your_refresh_token"
}

POST /api/token/verify is also available to check whether a token is still valid.

3. Use the token

Send the token in the request header when calling protected endpoints:

Authorization: Bearer <access token>

4. The parameter package (.qyp)

All model inputs live in one .qyp file — really just a zip, laid out like this:

para.toml                  model parameters (required)
para_geo.toml              geometry parameters (required for 3D)
pseudo_environ_data.json   environment data (optional)
pseudo_soil_data.json      soil data (optional)
*.obj / *.mtl              organ meshes
*.png                      textures

Files may sit at the root of the archive or inside a folder; the server always takes the directory holding para.toml as the plant root.

5. Listing models

GET /api/qingyuan/models

Returns the plant models this account can reach: its own, those shared with it, and public ones. Each entry carries the package download URL.

[
  {
    "slug": "demo-crop-tomsim-dwarf-tomato-l203",
    "name": "dwarf_tomato_L203",
    "labels": ["crop", "tomsim"],
    "author": "admin",
    "visibility": "public",
    "version": 1,
    "version_count": 1,
    "package_url": "/simulator/models/demo-crop-tomsim-dwarf-tomato-l203/package/"
  }
]

GET /api/qingyuan/models/{slug}/package

Download the .qyp of the model's current version.

6. Running a simulation

Upload a package and run it (multipart/form-data):

POST /api/qingyuan/run

file            the .qyp package
days            number of growth cycles; empty means the cycle from para.toml (max 500)
three_d         whether to build the 3D model, default false
svg             whether to build the topology diagram, default true
area_per_plant  ground area per plant in m², optional

Or run a model already stored on the server, with no upload:

POST /api/qingyuan/models/{slug}/run

{
    "days": 120,
    "three_d": true,
    "svg": true
}

Both return the same shape:

{
    "plant_name": "dwarf_tomato_L203",
    "days": 120,
    "results": [
        {"cu": 1, "leaf_area": 0.0, "biomass": 0.0, "demand": 0.0,
         "leaf_nums": 0, "flower_nums": 0, "fruit_nums": 0,
         "petiole_nums": 0, "internode_nums": 0,
         "leaf_weight": 0.0, "fruit_weight": 0.0, "root_weight": 0.0,
         "leaf_fresh_weight": 0.0, "fruit_fresh_weight": 0.0, ...}
    ],
    "svg":  "<svg ...>",   topology diagram
    "gltf": "{ ... }"      3D model, with textures and vertex data embedded
}

7. Try it with curl

TOKEN=$(curl -s -X POST http://<host>/api/token/pair \
  -H "Content-Type: application/json" \
  -d '{"username":"u","password":"p"}' | jq -r .access)

curl -X POST http://<host>/api/qingyuan/run \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@dwarf_tomato.qyp" \
  -F "days=120" -F "three_d=true"