Values

[pyrollo]

(DRAFT)

Model values are about to be merged.

There are several issues to address in a mid/long term;:

• They are only numeric but in the future they could be of various types (at least text, but may be boolean and placeables);
• They have a lot in common with virtual heightmaps;

Merge model values and heightmaps

Idea here is to elaborate a parameter system that merges heightmaps and model value in "values".

Instead of describing heightmaps like this:

sometaskrequiringheightmap:
  ...
  heightmap:
    sum:
      - ground
      - 10
  ...

We could use a value for Z:

sometaskrequiringaltitudedefinition:
  ...
  altitude:
    sum:
      - heightmap: ground
      - 10
  ...

the altitude object would be a value with (x,y) context (such value definition, involving heightmap, would be possible only where we have (x,y) in the context).

Context

Context tells what is available for value computation. For now, two contextual elements are identified but more may come:

• model
• position2d

Context depends on where value computation takes place.

Model context

Having a model in the context means value computation could access model metadata using metadata: operator:

  ...
  postProcessing:
   set: height
   as:
     product:
       - metadata: floors
       - 3

This will set height metadata as 3 * floors metadata for post-processed model.

Model context is available in:

• Models post-processor;
• Models tasks;

Position2d context

Having a position in contexts means we know where we are on map for value computation. So it's for example possible to fetch height from a heightmap using heightmap: operator:

sometask:
  type: setHeightmap
  heightmap: destination
  set:
    sum:
      - heightmap: origin
      - 10
   if:
     value:
        heightmap: origin
        greaterThan: 0

This (non yet existing) task will populate destination heightmap with origin heightmap altitude plus 10 if it is over 0.

Mixing contexts

Of course, a context could mix model and position. For example in a "render model task", we could access model metadata and position for a given computation.

On Params point of view

Value computation is invalid if it uses an unavailable context (metadata without model or heightmap without position).

This could either:

• Throw an exception when invalid operator encountered (easy but not satisfying);
• Be checked at validation time (better, but more complex);

Check during validation means we have to specify context in Parameter class:

public class XxxParams {
  ...
  public ValueWithPositionAndModelContextParams value;
  ...
}

Using classes for that will lead to a huge amount of classes (2 ^ (nb of context types)). There may be something better to do:

public class XxxParams {
  ...
  public ValueParams value;
  ...

  public void validate() {
     value.addModelContext();
     value.addPosition2dContext();
     value.validate();
  }
}

[indyteo]

On the Params implementation note:

We could explore how generics could help us defining the context. Maybe ValueParams<ModelContext> could help. It'll still require an interface per combination of context type.

Another idea could be to have just a ValueParams, but add an annotation to validate context (annotation being repeatable removes the need for cross product of context types):

@ValueContext(ModelContext.class)
@ValueContext(Position2dContext.class)
public ValueParams value;

Obviously both options will require works to properly handle them.

On the technical side, context could be represented as a Map<ContextKey, Object>, with extensible context keys (a module could easily add a new contextual element along with existing context data), which could look like:

class ContextKey<T> {
    private final Class<T> type;

    public ContextKey(Class<T> type) {
        this.type = type;
    }

    public <T> cast(Object obj) {
        return type.cast(obj);
    }
}

class StandardContextKeys {
    public static final ContextKey<Model> MODEL = new ContextKey<>(Model.class);
    public static final ContextKey<Position2d> POSITION_2D = new ContextKey<>(Position2d.class);
}

class Context {
    private final Map<ContextKey<?>, Object> values = new HashMap<>();

    public <T> void set(ContextKey<T> key, T value) {
        values.put(key, value);
    }

    // Or if we make context immutable, probably better, something like ".with(...)" returning new instance

    public <T> T get(ContextKey<T> key) {
        Object obj = values.get(key);
        if (obj == null)
            throw new NoSuchElementException("No context value for key: " + key);
        return key.cast(obj);
    }
}

class Somewhere {
    public void somewhere(Context context) {
        Model model = context.get(StandardContextKeys.MODEL);
    }
}

At first we could think it is not needed to have a "key", and we could just use a Map<Class, Object>, but it causes an issue if multiple values of the same type must represent different contexts. For example, if we want to have 2 different positions in the context (like, "current position" and "nearest neighbor position", idk...). Having a key allows to store multiple context elements of the same type, should it be needed.

[pyrollo]

Yaml proposal

In a first time, only model numeric values will be implemented.

Later, we will have typed values (string, number, maybe coordinates) and contextual values (allowing to get metadata model, or heightmap values, according to the context (being processing a model or not, having coordinates or not).

# Absent values
value:        
value: null

# Canonical literal values
value:
  string: toto
value:
  number: 3

# Shortcut literal values
value: foo    # the "foo" string
value: "null" # the "null" string
value: 0      # number 0

# Model metadata (needs a model to be in context)
value:
  metadata: bar

# Heightmap value (needs 2d coordinates to be in context)
value:
  heightmap: baz # Standard heightmap description, could be a computed heightmap

[pyrollo]

Another idea about contextual typed values:
Boolean values could replace model filters operators.