Bi-Grid Provider Service

Latest Version: v1.5.3

For Users: See Docker for how to install and run the application as a container.

API Usage: See RESTful Web Endpoints on how to query the service.

Visualize: Bi-grids created with this service can be visualized via https://github.com/UniAgent-Platform/bispace-viewer

For Developers: See How to Build and Start the Service if you want to build and run the service manually. This service is also available as a Java library.

Bi-Grid Provider Service

Bi-Grid Provider Service is a reactive Spring Boot REST API for generating rich, bigraph-style spatial location models — including grids, quadtrees, convex shapes, and interpolated lines.

Models are delivered in multiple formats:

XML: fully Ecore-compliant bigraph instance or meta-models
JSON: lightweight, custom serialization
Base64-encoded Protobuf: compact binary for efficient transmission

These location models are ideal for cyber-physical systems, simulation workflows, and formal consistency checks in reactive bigraph programs, enabling precise spatial reasoning and adaptive behaviors.

Features

Location Models

The service can generate and return parameterizable bigraph-style location models in XML, JSON, or Base64-encoded Protobuf formats:

Points: Randomly placed within a given boundary.
Uniform n×m Grids: Evenly spaced points with configurable origin and step sizes.
Quadtrees: Recursive spatial subdivision with a defined boundary.
Lines (Interpolated): Points generated along interpolated paths with custom step sizes.
Convex Shapes: Models generated from a convex polygon defined by an ordered point set.
Meta-model Retrieval: Obtain or create the core bigraph meta-model for schema validation.
CDO Repository Fetch: Retrieve existing models directly from a remote CDO server.

Ecore-Compliant Models

All XML outputs follow the Ecore standard from the Eclipse Modeling Framework (EMF), ensuring interoperability with model-driven engineering tools. Every bigraphical location model generated by this service strictly conforms to the Bigraph Ecore Metamodel (BEM), enabling seamless integration, validation, and transformation within EMF-based workflows.

RESTful Web Endpoints

Retrieve the Bi-Spatial Metamodel

You can retrieve the Ecore-based metamodel used for all bi-spatial location models. This metamodel defines the structure and types of the instance models (e.g., grids, interpolated trajectories) that your application will load or validate.

$ curl http://localhost:8080/generate/metamodel?format=xml

This metamodel is required to:

Validate location-based bigraph instance models.
Enable model-driven tools (e.g., EMF, Eclipse) to work with generated content.

Create Random Points

Within a default 2D rectangle (boundary) from (0,0) to (10,10):

$ curl "http://localhost:8080/generate/points/random?pointCount=10" \
-H "Content-Type: application/json"

Within a given rectangular boundary:

$ curl -X POST "http://localhost:8080/generate/points/random?pointCount=15" \
-H "Content-Type: application/json" \
-d '{
    "x": 0.0,
    "y": 0.0,
    "width": 15.0,
    "height": 15.0
}'

Arguments: ?pointCount=<INT>: maximum number of points to generate

Create a Quadtree

You have to supply points of the form as shown in the example. The output format can be specified via the format argument.

# The boundary is a necessary argument
$ curl -X POST "http://localhost:8080/generate/quadtree?format=xml" \
-H "Content-Type: application/json" \
-d '{
    "boundary": {
        "x": 0.0,
        "y": 0.0,
        "width": 10.0,
        "height": 10.0
    },
    "pointData": {
          "points": [
            {"x": 0.2, "y": 0.2},
            {"x": 1.0, "y": 2.0},
            {"x": 3.0, "y": 4.0}
          ]
    }
}'

# Set the margin of a point. This decides when to split the cells of the quadtree:
$ curl -X POST "http://localhost:8080/generate/quadtree?marginPoint=0.1&format=xml" \
-H "Content-Type: application/json" \
-d '{
    "boundary": {
        "x": -5.0,
        "y": -5.0,
        "width": 10.0,
        "height": 10.0
    },
    "pointData": {
          "points": [
            {"x": 4.0, "y": 0.2},
            {"x": 4.0, "y": -0.12},
            {"x": 4.0, "y": -0.1},
            {"x": 4.0, "y": 0.4}
          ]
    }
}'

# Protobuf Output Format
# Also: Set the maxTreeDepth manually (otherwise it is automatically computed based on the boundary and point margin
$ curl -X POST "http://localhost:8080/generate/quadtree?maxTreeDepth=4&format=protobuf" \
-H "Content-Type: application/json" \
-d '{
    "boundary": {
        "x": 0.0,
        "y": 0.0,
        "width": 10.0,
        "height": 10.0
    },
    "pointData": {
          "points": [
            {"x": 0.2, "y": 0.2},
            {"x": 1.0, "y": 2.0},
            {"x": 3.0, "y": 4.0}
          ]
    }
}'

Arguments:

Format: ?format=xml (Default), ?format=json, ?format=protobuf
Configurable margin around each point: ?marginPoint=<DOUBLE>
Configurable max points before subdivision: ?maxPointsPerLeaf=<INT>
Configurable max depth of the quadtree: ?maxTreeDepth=<INT>
- Is calculated automatically given the boundary and marginPoint

Interpolate Points

$ curl -X POST http://localhost:8080/generate/interpolated?format=xml \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
        {"x": 0, "y": 0},
        {"x": 1, "y": 1},
        {"x": 2, "y": 2}
    ],
    "stepSizeX": 0.25,
    "stepSizeY": 0.25
  }'
  
# Protobuf Messages format
$ curl -X POST http://localhost:8080/generate/interpolated?format=protobuf \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
        {"x": 0, "y": 0},
        {"x": 1, "y": 1},
        {"x": 2, "y": 2}
    ],
    "stepSizeX": 0.25,
    "stepSizeY": 0.25
  }'

Arguments:

Format: ?format=xml (Default), ?format=json, ?format=protobuf

Generate a Bi-Spatial Convex Shape

This endpoint creates a bi-spatial bigraph model based on a custom list of 2D points that define a convex polygon. The interior of the shape is rasterized using a specified step size, and a spatial location node is generated for each rasterized point.

This generates a convex bi-spatial structure from a list of polygon vertices:

$ curl -X POST http://localhost:8080/generate/convex \
  -H "Content-Type: application/json" \
  -d '{
        "stepSize": 0.25,
        "points": [
          { "x": 0.0, "y": 0.0 },
          { "x": -1.24, "y": 0.58 },
          { "x": 2.86, "y": 2.93 },
          { "x": 3.08, "y": 0.0 }
        ]
      }'
    
# Protobuf Messages format
$ curl -X POST http://localhost:8080/generate/convex?format=protobuf \
  -H "Content-Type: application/json" \
  -d '{
        "stepSize": 0.25,
        "points": [
          { "x": 0.0, "y": 0.0 },
          { "x": -1.24, "y": 0.58 },
          { "x": 2.86, "y": 2.93 },
          { "x": 3.08, "y": 0.0 }
        ]
      }'

Arguments:

Format: ?format=xml (Default), ?format=json, ?format=protobuf
Step Size (required): included in body → "stepSize": 0.25

Use Cases:

Defining irregular regions of interest in a spatial simulation.
Modeling bounded areas in drone or robot navigation maps.
Loading custom-shaped digital twin spaces into your application.

Generate a Uniform Bi-Spatial Grid

These endpoints allow you to generate a uniform grid-based bi-spatial bigraph model, which serves as a spatial structure of discrete locations. The grid can be used as a base layout for simulation, visualization, or as part of a digital twin model.

Example: Generate a default 3x3 grid with step size 1.0 in both directions, where the origin is at (x,y) = (0,0):

$ curl http://localhost:8080/generate/bigrid
$ curl "http://localhost:8080/generate/bigrid?rows=4&cols=2&format=xml"
$ curl "http://localhost:8080/generate/bigrid?rows=2&cols=2&format=protobuf"

To adjust the default values:

# Default Parameters (3x3)
$ curl -X POST http://localhost:8080/generate/bigrid \
  -H "Content-Type: application/json" \
  -d '{"x":0,"y":0,"stepSizeX":1.5,"stepSizeY":2.0}'

# With Parameters
$ curl -X POST "http://localhost:8080/generate/bigrid?rows=6&cols=6" \
  -H "Content-Type: application/json" \
  -d '{"x":0,"y":0,"stepSizeX":0.5,"stepSizeY":0.5}'

Generate a Uniform Bi-Spatial Grid with Directional Route

These endpoints allow you to generate a uniform grid-based bi-spatial bigraph model with directional route, which serves as a more detailed spatial structure of discrete locations. Added nodes such as "LeftRoute", "RightRoute", "ForwardRoute" and "BackRoute" to indicate the direction of connections to other Locales.

# Acquire directional bi-grid metamodel
curl http://localhost:8080/generate/directional/metamodel

# Generate a default 3x3 directional bi-grid
curl http://localhost:8080/generate/directional/bigrid

# Generate a 4x2 directional bi-grid
curl "http://localhost:8080/generate/directional/bigrid?rows=4&cols=2"

# Directional bi-grid with custom parameters
curl -X POST "http://localhost:8080/generate/directional/bigrid?rows=6&cols=6" \
  -H "Content-Type: application/json" \
  -d '{"x":0,"y":0,"stepSizeX":0.5,"stepSizeY":0.5}'

Arguments:

Format: ?format=xml (Default), ?format=json, ?format=protobuf
Rows (default: 3): ?rows=3
Columns (default: 3): ?cols=3

Generate a Uniform Bi-Spatial Grid with Diagonal Directional Route

These endpoints allow you to generate a uniform grid-based bi-spatial bigraph model with 8-directional routes, which provides the most comprehensive spatial structure including diagonal connections. Added nodes include all cardinal directions ("LeftRoute", "RightRoute", "ForwardRoute", "BackRoute") plus diagonal directions ("ForwardLeftRoute", "ForwardRightRoute", "BackLeftRoute", "BackRightRoute").

# Acquire diagonal directional bi-grid metamodel
curl http://localhost:8080/generate/diagonal-directional/metamodel

# Generate a default 3x3 diagonal directional bi-grid
curl http://localhost:8080/generate/diagonal-directional/bigrid

# Generate a 4x2 diagonal directional bi-grid
curl "http://localhost:8080/generate/diagonal-directional/bigrid?rows=4&cols=2"

# Diagonal directional bi-grid with custom parameters
curl -X POST "http://localhost:8080/generate/diagonal-directional/bigrid?rows=6&cols=6" \
  -H "Content-Type: application/json" \
  -d '{"x":0,"y":0,"stepSizeX":0.5,"stepSizeY":0.5}'

8 Directions Explained:

Cardinal (4): Forward, Back, Left, Right
Diagonal (4): ForwardLeft, ForwardRight, BackLeft, BackRight

Arguments:

Format: ?format=xml (Default), ?format=json, ?format=protobuf
Rows (default: 3): ?rows=3
Columns (default: 3): ?cols=3

Generate a Three-Dimensional Diagonal Directional Bi-Spatial Grid

These endpoints allow you to generate a 3D uniform grid-based bi-spatial bigraph model with diagonal directional routes, which consists of multiple layers of 2D diagonal directional grids connected vertically. Each locale can connect in up to 10 directions: 8 horizontal directions (4 cardinal + 4 diagonal) plus 2 vertical directions (up and down).

# Acquire 3D diagonal directional bi-grid metamodel
curl http://localhost:8080/generate/3d-diagonal-directional/metamodel

# Generate a default 3x3x3 (rows x cols x layers) 3D diagonal directional bi-grid
curl http://localhost:8080/generate/3d-diagonal-directional/bigrid

# Generate a 4x4x5 3D diagonal directional bi-grid
curl "http://localhost:8080/generate/3d-diagonal-directional/bigrid?rows=4&cols=4&layers=5"

# 3D diagonal directional bi-grid with custom parameters
curl -X POST "http://localhost:8080/generate/3d-diagonal-directional/bigrid?rows=5&cols=5&layers=3" \
  -H "Content-Type: application/json" \
  -d '{"x":0,"y":0,"z":0,"stepSizeX":1.0,"stepSizeY":1.0,"layerHeight":2.0}'

Arguments:

Format: ?format=xml (Default), ?format=json, ?format=protobuf
Rows (default: 3): ?rows=3
Columns (default: 3): ?cols=3
Layers (default: 3): ?layers=3
Layer Height: Specified in request body JSON as layerHeight (default: 1.0)

Fetch a CDO Model

You can fetch an existing CDO-based bigraph model directly from a remote repository. This is useful when working with shared models stored in a collaborative EMF/CDO setup.

$ curl "http://localhost:8080/fetch/cdo?address=cdo.server:2036&repopath=/my/model/path&format=xml"
$ curl "http://localhost:8080/fetch/cdo?address=cdo.server:2036&repopath=/system&resFactor=1.0&format=protobuf"

Arguments:

Address: ?address=127.0.0.1:2036 — CDO server host and port
RepoPath: ?repopath=/system — Path to the resource in the CDO repository
Format: ?format=xml (Default), ?format=json, ?format=protobuf

How to Build and Start the Service

1. Building:

$ ./mvnw clean package -DskipTests

2. Running:

$ java -jar ./bin/bigrid-provider-service.jar

Configuration

Parameter	Default	Command-Line	System Property	Environment Variable
Port	8080	`--server.port=9090`	`-Dserver.port=9090`	`export SERVER_PORT=9090`

Example:

# Command-Line
$ java -jar bigrid-provider-service.jar --server.port=9090

# System Property
$ java -Dserver.port=9090 -jar bigrid-provider-service.jar

# Environment Variable
$ export SERVER_PORT=9090 && java -jar bigrid-provider-service.jar

Order of Priority:

Spring Boot evaluates properties in this order:

Command-line arguments (the highest priority)
Environment variables
application.properties
Default configuration (the lowest priority)

Library: Build Configuration

Library mode (JAR without spring-boot plugin):

$ mvn clean install -Plib -DskipTests

Docker Container

1. Build the image:

$ docker build -t bigrid-provider-service .

2. Run the container:

$ docker run -p 8080:8080 bigrid-provider-service

# Allow reaching the host from inside a container
$ docker run --network=host bigrid-provider-service

Change the port (optional):

$ docker run -p 9090:9090 \
  -e "SPRING_APPLICATION_JSON={\"server.port\":9090}" \
  bigrid-provider-service

Contributing

Contributions are welcomed from the open source community! To get started:

See CONTRIBUTING.md for guidelines on how to propose changes or submit pull requests.
Please review our CODE_OF_CONDUCT.md to foster an inclusive and respectful environment.

License

This project is licensed under the Apache License 2.0.

You are free to use, modify, and distribute this software in accordance with the license terms.

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.mvn/wrapper		.mvn/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Bi-Grid Provider Service

Features

Location Models

Ecore-Compliant Models

RESTful Web Endpoints

Retrieve the Bi-Spatial Metamodel

Create Random Points

Create a Quadtree

Interpolate Points

Generate a Bi-Spatial Convex Shape

Generate a Uniform Bi-Spatial Grid

Generate a Uniform Bi-Spatial Grid with Directional Route

Generate a Uniform Bi-Spatial Grid with Diagonal Directional Route

Generate a Three-Dimensional Diagonal Directional Bi-Spatial Grid

Fetch a CDO Model

How to Build and Start the Service

Configuration

Library: Build Configuration

Docker Container

Contributing

License

About

Uh oh!

Releases

Packages

Languages

License

ShaneCan/bigrid-provider-service

Folders and files

Latest commit

History

Repository files navigation

Bi-Grid Provider Service

Features

Location Models

Ecore-Compliant Models

RESTful Web Endpoints

Retrieve the Bi-Spatial Metamodel

Create Random Points

Create a Quadtree

Interpolate Points

Generate a Bi-Spatial Convex Shape

Generate a Uniform Bi-Spatial Grid

Generate a Uniform Bi-Spatial Grid with Directional Route

Generate a Uniform Bi-Spatial Grid with Diagonal Directional Route

Generate a Three-Dimensional Diagonal Directional Bi-Spatial Grid

Fetch a CDO Model

How to Build and Start the Service

Configuration

Library: Build Configuration

Docker Container

Contributing

License

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages