Module msquares

Corona binding of Philip Allan Rideout's msquares.

To use the plugin, add the following in build.settings:

plugins = {
   ["plugin.msquares"] = { publisherId = "com.xibalbastudios" }
 }

Sample code is available here.

The Bytes type—specified in a few of the bytemap methods—may be any object that implements ByteReader, including strings.

From par_msquares.h:

Converts fp32 grayscale images, or 8-bit color images, into triangles.

For grayscale images, a threshold is specified to determine insideness. For color images, an exact color is specified to determine insideness. Color images can be r8, rg16, rgb24, or rgba32.

For a visual overview of the API and all the flags, see http://github.prideout.net/marching-squares.

The MIT License Copyright (c) 2015 Philip Rideout

Functions

color (data, w, h, cell_size, color, bpp, flags) Generate meshes by marching over color data.
color_multi (data, w, h, cell_size, bpp, flags) Generate per-color meshes by marching over color data.
grayscale (data, w, h, cell_size, threshold, flags) Generate meshes by marching over grayscale data.
grayscale_multi (data, w, h, cell_size, thresholds, flags) Using several thresholds, performs multiple marches over grayscale data.
Proxy:GetMode ()
Proxy:Reset () Explictly remove any reference to a Mesh, allowing it to be garbage-collected.
NewProxy () Create a proxy for use by Mesh:GetPoints or Mesh:GetTriangles.
MeshList:GetMesh (index) Get an immutable reference to one of the list's meshes.
MeshList:__len ()
Mesh:GetBoundary () Extract the polyline boundary, composed of one or more chains.
Mesh:GetColor ()
Mesh:GetDim ()
Mesh:GetNumPoints ()
Mesh:GetNumTriangles ()
Mesh:GetPoints ([opts])
Mesh:GetTriangles ([opts])


Functions

color (data, w, h, cell_size, color, bpp, flags)
Generate meshes by marching over color data.

Parameters:

  • data Bytes Color data.

    If less than w * h * bpp in size, an internal copy with padding zeroes is created, which is a potential performance hit.

  • w uint Width of bitmap...
  • h uint ...and height.
  • cell_size uint Size of marching squares cell. Both w and h must be a multiple of this size.
  • color uint Pixels that have this value are regarded as being inside.

    This is a 32-bit value layed out either as A|B|G|R or A|R|G|B, with A in the high byte. (To convert these octets to Corona color components, divide by 255.)

  • bpp uint Bytes per pixel, from 1 to 4.
  • flags string, {string,...} or nil Flags describing the operation and its results.

    As an array, some combination of the following:

    • "HEIGHTS": Requests that returned meshes have 3-tuple coordinates instead of 2-tuples. When using a color-based function, the Z coordinate represents the nearest pixel's alpha.
    • "CONNECT": Adds extrusion triangles to each mesh other than the lowest mesh. (This implies the HEIGHTS flag, which will be added as a convenience if absent.)
    • "DUAL": Returns a meshlist with two meshes: one for the inside, one for the outside.
    • "SNAP": Applies a step function to the Z coordinates. (This implies the HEIGHTS and DUAL flags, which will be added as a convenience if absent.)
    • "SWIZZLE": Indicates that color is ABGR instead of ARGB.
    • "INVERT": Reverses the "insideness" test.
    • "SIMPLIFY": Enables quick & dirty (not best) simpification of the returned mesh.

    As a string, any of the above.

Returns:

    MeshList List of one or more resulting meshes.
color_multi (data, w, h, cell_size, bpp, flags)
Generate per-color meshes by marching over color data.

Parameters:

  • data Bytes As per color, but may contain at most 256 distinct colors.
  • w uint Width of bitmap...
  • h uint ...and height.
  • cell_size uint As per color.
  • bpp uint Bytes per pixel, from 1 to 4.
  • flags string, {string,...} or nil As per color, but with the following addition:

    • "CLEAN": Ensures there are no T-junction vertices. (If present, SIMPLIFY is ignored.)

    Additionally, the SNAP, INVERT, and DUAL flags are ignored.

Returns:

    MeshList List of one or more resulting meshes.
grayscale (data, w, h, cell_size, threshold, flags)
Generate meshes by marching over grayscale data.

Parameters:

  • data Bytes or {number,...} This may be an array of numbers in [0, 1].

    In Bytes form, this will typically be contiguous array of 32-bit floats. When the octets flag is specified, however, data is interpreted as an array of 8-bit unsigned integers that are remapped to [0, 1].

    If fewer than w * h elements are available, an internal copy with padding zeroes is created, for a potential performance hit. (N.B. Non-float data entails some of these conversions anyhow.)

  • w uint Width of bitmap...
  • h uint ...and height.
  • cell_size uint As per color.
  • threshold number Values in data greater than the threshold are regarded as inside.
  • flags string, {string,...} or nil

    As per color, with the following addition:

    • "as_octets": Interpret Bytes-type data as 8-bit values, as described above.

Returns:

    MeshList List of one or more resulting meshes.
grayscale_multi (data, w, h, cell_size, thresholds, flags)
Using several thresholds, performs multiple marches over grayscale data. Several intermediate meshes are generated along the way and merged at the end.

Parameters:

  • data Bytes or {number,...} As per grayscale.
  • w uint Width of bitmap...
  • h uint ...and height.
  • cell_size uint As per color.
  • thresholds Bytes or {number,...} One or more thresholds, which should be in order. Representation-wise, this is like data.

    The following ranges are visited:

    (-∞, threshold #1), [threshold #1, threshold #2), ..., [threshold #n, +∞)

    For each range, values in data ≥ low and < high are regarded as inside the corresponding mesh.

  • flags string, {string,...} or nil

    As per grayscale, with the following addition:

    • "threshold_as_octets": Interpret Bytes-type thresholds as 8-bit values, cf. grayscale.

Returns:

    MeshList List of one or more resulting meshes.
Proxy:GetMode ()

Returns:

    string One of "none", "points", or "triangles" describing the proxy's current binding.
Proxy:Reset ()
Explictly remove any reference to a Mesh, allowing it to be garbage-collected.

When a proxy is bound to another Mesh, this is done implicitly beforehand.

Without such a reference, the proxy is a 0-length empty Bytes.

NewProxy ()
Create a proxy for use by Mesh:GetPoints or Mesh:GetTriangles.

Returns:

    Proxy Used to provide a Bytes view over a Mesh's data.
MeshList:GetMesh (index)
Get an immutable reference to one of the list's meshes.

Parameters:

  • index uint Mesh index, from 1 to #self.

Returns:

    Mesh Mesh reference.
MeshList:__len ()

Returns:

    uint Mesh count.
Mesh:GetBoundary ()
Extract the polyline boundary, composed of one or more chains.

Counterclockwise chains are solid, clockwise chains are holes. So, when serializing to SVG, all chains can be aggregated in a single <path>, provided they each terminate with a "Z" and use the default fill rule.

Returns:

    {{number,...},...} or nil One or more arrays of points of the form { ..., x, y, ... } or { ..., x, y, z, ... }, according to the mesh's dimensions. See Mesh:GetPoints regarding normalization.

    In the case of a degenerate mesh (no points / triangles), returns nil.

Mesh:GetColor ()

Returns:

    uint If the mesh was created by color_multi, the mesh-specific color. (See the notes about color is color.) Otherwise, 0.
Mesh:GetDim ()

Returns:

    uint Mesh dimensions, either 2 or 3.
Mesh:GetNumPoints ()

Returns:

    uint Number of points.
Mesh:GetNumTriangles ()

Returns:

    uint Number of triangles.
Mesh:GetPoints ([opts])

Parameters:

  • opts table Getter options, which include:

    • out: This may be a Proxy, in which case it is bound to the mesh's points and returned.

    Otherwise, points are supplied as a table, either using the one provided here or creating a new one.

    N.B. With a custom table, any entries not overwritten will be left as-is. If necessary, use self:GetNumTriangles() * self:GetDim() to calculate the number of entries. (optional)

Returns:

    Proxy or table As a table, an array { x1, y1, ... } or { x1, y1, z1, ... }, according to the mesh's dimensions, whose values are numbers. The x and y values will be normalized to [0, 1] (coordinates are scaled by 1 / max(width, height), using the bitmap dimensions, e.g. in color).

    Otherwise, the Proxy supplied as opts.out.

Mesh:GetTriangles ([opts])

Parameters:

  • opts table Getter options, which include:

    • one_based: Triangle indices are one-based, rather zero-based? Ignored for Proxy results.
    • out: This may be a Proxy, in which case it is bound to the mesh's triangles and returned.

    Otherwise, indices are supplied as a table, either using the one provided here or creating a new one.

    N.B. With a custom table, any entries not overwritten will be left as-is. If necessary, use self:GetNumTriangles() * 3 to calculate the number of entries. (optional)

Returns:

    Proxy or table As a table, an array { index1, index2, index3, ... } whose values are uints.

    Otherwise, the Proxy supplied as opts.out.

generated by LDoc 1.4.6 Last updated 2018-08-16 17:59:26