FeatureSerializer

public final class FeatureSerializer

The FeatureSerializer is used to both serialize and parse Feature objects. This is beneficial when you want to re-use RoundedPolygon objects created by SvgPathParser, as parsing serialized Feature objects is more performant than using the svg path import.

Example:

// Do the following three *once*
val triangleSVGPath: String = "M0,0 0.5,1 1,0Z"
val triangleFeatures: List<Feature> = SvgPathParser.parseFeatures(triangleSVGPath)
val serializedTriangle: String = FeatureSerializer.serialize(triangleFeatures)

// Parse the serialized triangle features in your production code.
// You can adjust them (e.g. the type) however you want before parsing.
val features: List<Feature> = FeatureSerializer.parse(serializedTriangle)
val triangle: RoundedPolygon = RoundedPolygon(features, centerX = 0.5f, centerY = 0.5f)
Morph(triangle, ...)

Summary

Public methods
static final @NonNull List<@NonNull Feature>
parse(@NonNull String serializedFeatures)

Parses a serialized string representation of Feature into their object representations, adhering to version 1 of the feature serialization format.
static final @NonNull String

Serializes a list of Feature objects into a string representation, adhering to version 1 of the feature serialization format.

Public methods

parse

Added in 1.1.0-alpha01
public static final @NonNull List<@NonNull Feature> parse(@NonNull String serializedFeatures)

Parses a serialized string representation of Feature into their object representations, adhering to version 1 of the feature serialization format.

The serialized string must adhere to the format generated by FeatureSerializer.serialize. This format consists of:

  1. Version Identifier: A 'V' followed by the version number (e.g., 'V1').

  2. Feature Serialization: Each Feature is serialized individually and concatenated.

    • Feature Tag: A single-character tag identifies the feature type:

      • 'n': Edge

      • 'x': Convex Corner

      • 'o': Concave Corner

      • Any other tags unknown to version 1 will default to an edge interpretation.

    • Cubic Serialization: Each Cubic within a feature is serialized as a sequence of comma-separated x,y coordinates. Subsequent cubics within a feature omit their first anchor points, as they're identical to their predecessors' last anchor points.

Note: The current version (1) of the serialization format is stable. However, future versions may introduce incompatible changes with version 1. The default behavior for unknown or missing versions will be version 1 parsing. If you have a later version string, update the library to the latest version.

Parameters
@NonNull String serializedFeatures

The serialized Feature objects in a concatenated String.
Returns
@NonNull List<@NonNull Feature>

A list of parsed Feature objects, corresponding to the serialized input.
Throws
kotlin.IllegalArgumentException

  • if a serialized string lacks sufficient points to create Cubic objects with
kotlin.IllegalArgumentException

  • if no feature tags could be found
kotlin.NumberFormatException

  • if the Cubics' coordinates aren't valid representations of numbers.

serialize

public static final @NonNull String serialize(@NonNull List<@NonNull Feature> features)

Serializes a list of Feature objects into a string representation, adhering to version 1 of the feature serialization format.

Format:

  1. Version Identifier: A 'V' followed by the version number (e.g., 'V1').

  2. Feature Serialization: Each Feature is serialized individually and concatenated.

    • Feature Tag: A single-character tag identifies the feature type:

      • 'n': Edge

      • 'x': Convex Corner

      • 'o': Concave Corner

    • Cubic Serialization: Each Cubic within a feature is serialized as a sequence of comma-separated x,y coordinates. Subsequent cubics within a feature omit their first anchor points, as they're identical to their predecessors' last anchor points.

Example: Given two features:

  • An edge with one Cubic: { (0, 0), (1, 1), (2, 2), (3, 3) }

  • A convex corner with two Cubic objects: { (0, 0), (1, 1), (2, 2), (3, 3) }, { (3, 3), (4, 4), (5, 5), (6, 6) }

The serialized string would be:

V1 n 0,0, 1,1, 2,2, 3,3  x 0,0, 1,1, 2,2, 3,3, 4,4, 5,5, 6,6
Parameters
@NonNull List<@NonNull Feature> features

The list of Feature objects to serialize.
Returns
@NonNull String

The serialized string representation of the features