Latest Version: v1.5.2

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

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.

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

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

BiGrid 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.

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.

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.

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.

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

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

$ 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

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.

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}'

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 bigrid metamodel
curl http://localhost:8080/generate/directional/metamodel

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

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

# Directional bigrid 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

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

1. Building:

$ ./mvnw clean package -DskipTests

2. Running:

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

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 mode (JAR without spring-boot plugin):

$ mvn clean install -Plib -DskipTests

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

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.

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.