Direct component visualization (#98)

* Add default metadata map

* Add show for CoordinateSystem

* Add dark theme and theme preference

* Add CS graphics test

* Add workflow tip for graphical display

* Make render functions return CS, explain VS Code display more

Author: gpeairs

docs/src/coordinate_systems.md

@@ -44,6 +44,7 @@ the GDSII format. Accordingly, they hold `Polygon`s with metadata of type `GDSMe
     CellArray
     CellReference
     GDSMeta
+    gdslayers(::Cell)
     render!(::Cell, ::Polygon, ::GDSMeta)
     DeviceLayout.save(::File{format"GDS"}, ::Cell, ::Cell...)
 ```
@@ -97,8 +98,6 @@ Unlike `Cell`s, a `CoordinateSystem` is not tied to a database unit (a GDSII con
 
 Since `CoordinateSystem`s are intended to be backend-agnostic, a useful pattern is to give
 coordinate objects "semantic" metadata, consisting of a layer name `Symbol` as well as `level` and `index` attributes.
-This metadata can then be processed with designer-provided methods when rendering to an
-output format.
 
 ```@docs
     SemanticMeta
@@ -108,12 +107,13 @@ output format.
     level
 ```
 
-This means that a `CoordinateSystem` can be rendered to a `Cell` for output to a GDS format.
-During rendering, an `entity::GeometryEntity` with metadata `SemanticMeta(:ground_plane)` would be mapped to `to_polygons(entity)` with GDS layer number and datatype (for example, `GDSMeta(1,0)`) corresponding to the ground plane according to a mapping function `map_meta` provided to `render!`.
+A `CoordinateSystem` (or any `GeometryStructure`) can be rendered to a `Cell` for output to a GDS format by mapping its metadata to GDSMeta. Specifically, during rendering, an `entity::GeometryEntity` with metadata `SemanticMeta(:my_layer)` will be rendered as one or more polygons (`to_polygons(entity)`). These polygons will have GDSMeta (layer number and datatype) determined by `map_meta(SemanticMeta(:my_layer))`, where `map_meta` is a function supplied as a keyword argument to `render!`. A default hash-based map is supplied to allow quick visualizations when the specific output GDS layers don't matter.
 
 ```@docs
     Cell(::CoordinateSystem{S}) where {S}
     render!(::Cell, ::DeviceLayout.GeometryStructure)
+    DeviceLayout.default_meta_map
+    gdslayers(::DeviceLayout.GeometryStructure)
 ```
 
 Note that `Cell`s inherit the names of rendered `CoordinateSystem`s, so the original coordinate systems ought to have unique names (for example using [`uniquename`](@ref)).

docs/src/fileio.md

@@ -21,8 +21,6 @@ Using the [Cairo graphics library](https://cairographics.org), it is possible to
 cells into SVG, PDF, and EPS vector graphics formats, or into the PNG raster graphic
 format. This enables patterns to be displayed in web browsers, publications, presentations,
 and so on. You can save a cell to a graphics file by, e.g. `save("/path/to/file.svg", mycell)`.
-Note that cell references and arrays are not saved, so you should flatten cells if desired
-before saving them.
 
 Possible keyword arguments include:
 

docs/src/geometrylevel.md

@@ -88,17 +88,15 @@ The entities making up the `Path` are rendered into `Polygon`s, but the `Geometr
 Let's see how it looks:
 
 ```@example 1
-save("dogbone_path.svg", flatten(c); layercolors=Dict(0 => (0, 0, 0, 1), 1 => (1, 0, 0, 1)));
+save("dogbone_path.svg", c; layercolors=Dict(0 => (0, 0, 0, 1), 1 => (1, 0, 0, 1)));
 nothing; # hide
 ```
 
 ```@raw html
 <img src="../dogbone_path.svg" style="width: 3in;"/>
 ```
 
-!!! info
-    
-    The SVG backend only draws the top-level `Cell`, so it's necessary to [`flatten`](./geometry.md#Flattening) the cell before saving. `flatten` traverses references to place all entities in a single `Cell`, applying transformations as necessary. For further examples, we'll hide the line that flattens and saves to SVG just to display a cell.
+For further examples, we'll hide the line that saves to SVG just to display a cell.
 
 We can also add `Cell` references directly to a `Cell`, for example to apply a global rotation:
 

docs/src/index.md

@@ -106,7 +106,7 @@ attach!(
 )
 c = Cell("decoratedpath", nm)
 render!(c, p, GDSMeta(0))
-save("units.svg", flatten(c); layercolors=Dict(0 => (0, 0, 0, 1), 1 => (1, 0, 0, 1)));
+save("units.svg", c; layercolors=Dict(0 => (0, 0, 0, 1), 1 => (1, 0, 0, 1)));
 nothing; # hide
 ```
 
@@ -167,3 +167,5 @@ main() # execute main() at end of script.
 In a typical workflow, you'll have a text editor open alongside a Julia REPL. You'll save the above code in a file (e.g., `mycad.jl`) and then run `include("mycad.jl")` from the Julia REPL to generate your pattern.
 You'll iteratively revise `mycad.jl` and save your changes.
 Subsequent runs should be several times faster than the first, if you `include` the file again from the same Julia session.
+
+If you use a REPL started by the Julia for VS Code extension (`Alt+J Alt+O`), then objects that can be displayed graphically (`Cells` and `CoordinateSystems`) will be shown in a separate tab when returned by REPL execution. This display is not updated interactively with every command, but running `julia> my_cs` will show the latest version. You can zoom in and out to inspect details by holding `Command` (Mac) or `Alt` and scrolling.

src/DeviceLayout.jl

@@ -528,8 +528,8 @@ export Paths,
     undecorated
 
 include("cells.jl")
-import .Cells: Cell, CellReference, CellArray, cell, layers, text!
-export Cells, Cell, CellReference, CellArray, cell, layers, text!
+import .Cells: Cell, CellReference, CellArray, cell, gdslayers, layers, text!
+export Cells, Cell, CellReference, CellArray, cell, gdslayers, layers, text!
 
 include("utils.jl")
 

src/backends/graphics.jl

@@ -3,7 +3,9 @@ using Unitful
 import Unitful: Length, inch, ustrip
 import Cairo
 
-import DeviceLayout: bounds, datatype, gdslayer, load, save
+import DeviceLayout:
+    bounds, datatype, default_meta_map, element_metadata, gdslayer, load, save, to_polygons
+import DeviceLayout: CoordinateSystem, GeometryEntity
 using ..Points
 using ..Transformations
 import ..Rectangles: Rectangle, width, height
@@ -13,16 +15,61 @@ using ..Cells
 import FileIO: File, @format_str, stream
 
 using ColorSchemes
+using Preferences
 
-using ColorSchemes
-# Glasbey color scheme for categorical data (version avoiding greys and light colors)
-lcolor(l, scheme=:glasbey_bw_minc_20_maxl_70_n256) = # Make transparent
-    (
-        colorschemes[scheme][l + 1].r,
-        colorschemes[scheme][l + 1].g,
-        colorschemes[scheme][l + 1].b,
-        0.5
-    )
+# Available color schemes -- Glasbey themes for categorical data
+const LIGHT_MODE_SCHEME = :glasbey_bw_minc_20_maxl_70_n256  # Good for light backgrounds
+const DARK_MODE_SCHEME = :glasbey_bw_minc_20_minl_30_n256   # Good for dark backgrounds
+
+# Preference key for color theme
+const COLOR_THEME_PREF = "color_theme"
+
+"""
+    get_color_scheme()
+
+Get the current color scheme based on user preferences.
+Returns either `:glasbey_bw_minc_20_maxl_70_n256` (light theme) or
+`:glasbey_bw_minc_20_minl_30_n256` (dark theme).
+
+The default is light theme.
+"""
+function get_color_scheme()
+    scheme_name = @load_preference(COLOR_THEME_PREF, "light")
+    return scheme_name == "dark" ? DARK_MODE_SCHEME : LIGHT_MODE_SCHEME
+end
+
+"""
+    set_theme!(theme::String)
+
+Set the color scheme for graphics based on background lightness (`"light"` or `"dark"`).
+
+Light theme uses `:glasbey_bw_minc_20_maxl_70_n256` (avoids light colors, good for light backgrounds).
+
+Dark theme uses `:glasbey_bw_minc_20_minl_30_n256` (avoids dark colors, good for dark backgrounds).
+"""
+function set_theme!(theme::String)
+    if theme ∉ ["light", "dark"]
+        error("Theme must be 'light' or 'dark', got: '$theme'")
+    end
+    @set_preferences!(COLOR_THEME_PREF => theme)
+    for i = 0:255
+        layercolors[i] = lcolor(i)
+    end
+    @info "Color scheme set for '$theme' theme."
+end
+
+# Generate layer color with transparency
+lcolor(l, scheme) = (
+    colorschemes[scheme][l + 1].r,
+    colorschemes[scheme][l + 1].g,
+    colorschemes[scheme][l + 1].b,
+    0.5
+)
+
+# Use preference-based color scheme
+lcolor(l) = lcolor(l, get_color_scheme())
+
+# Initialize layercolors with the preferred scheme
 const layercolors = Dict([(i => lcolor(i)) for i = 0:255]...)
 
 function fillcolor(options, layer)
@@ -43,10 +90,16 @@ MIMETypes = Union{
     MIME"application/pdf",
     MIME"application/postscript"
 }
-function Base.show(io, mime::MIMETypes, c0::Cell{T}; options...) where {T}
+function Base.show(
+    io,
+    mime::MIMETypes,
+    geom::Union{Cell{T}, CoordinateSystem{T}};
+    options...
+) where {T}
+    c0 = flatten(geom)
     opt = Dict{Symbol, Any}(options)
-    bnd = ustrip(bounds(c0))
-    w, h = width(bnd), height(bnd)
+    bnd = bounds(c0)
+    w, h = width(ustrip(bnd)), height(ustrip(bnd))
     w1 = haskey(opt, :width) ? lscale(opt[:width]) : 4 * 72
     h1 = haskey(opt, :height) ? lscale(opt[:height]) : 4 * 72
     bboxes = haskey(opt, :bboxes) ? opt[:bboxes] : false
@@ -71,7 +124,7 @@ function Base.show(io, mime::MIMETypes, c0::Cell{T}; options...) where {T}
         Cairo.fill(ctx)
     end
 
-    ly = collect(layers(c0))
+    ly = collect(gdslayers(c0))
     trans = Translation(-bnd.ll.x, bnd.ur.y) ∘ XReflection()
 
     sf = min(w1 / w, h1 / h)
@@ -80,8 +133,8 @@ function Base.show(io, mime::MIMETypes, c0::Cell{T}; options...) where {T}
     for l in sort(ly)
         Cairo.save(ctx)
         Cairo.set_source_rgba(ctx, fillcolor(options, l)...)
-        for p in c0.elements[gdslayer.(c0.element_metadata) .== l]
-            poly!(ctx, trans.(ustrip(points(p))))
+        for el in c0.elements[gdslayer.(default_meta_map.(element_metadata(c0))) .== l]
+            poly!(ctx, trans(el))
         end
         Cairo.fill(ctx)
         Cairo.restore(ctx)
@@ -122,6 +175,10 @@ function poly!(cr::Cairo.CairoContext, pts)
     return Cairo.close_path(cr)
 end
 
+poly!(cr::Cairo.CairoContext, p::Polygon) = poly!(cr, ustrip(points(p)))
+poly!(cr::Cairo.CairoContext, ps::Vector{<:Polygon}) = poly!.(Ref(cr), ps)
+poly!(cr::Cairo.CairoContext, ent::GeometryEntity) = poly!(cr, to_polygons(ent))
+
 function save(f::File{format"SVG"}, c0::Cell; options...)
     open(f, "w") do s
         io = stream(s)

src/cells.jl

@@ -24,7 +24,7 @@ import DeviceLayout:
 import DeviceLayout: flatten, flatten!, order!, traverse!, uniquename # to re-export
 
 export Cell, CellArray, CellReference
-export cell, dbscale, layers, flatten, flatten!, order!, traverse!, uniquename
+export cell, dbscale, layers, gdslayers, flatten, flatten!, order!, traverse!, uniquename
 
 # Avoid circular definitions
 abstract type AbstractCell{S} <: AbstractCoordinateSystem{S} end
@@ -247,13 +247,25 @@ function CoordinateSystems.append_coordsys!(
 end
 
 """
-    layers(x::Cell)
+    gdslayers(x::Cell)
 
-Returns the GDS layers of elements in cell `x` as a set. Does *not* return the layers
+Returns the unique GDS layers of elements in cell `x`. Does *not* return the layers
 in referenced or arrayed cells.
 """
+gdslayers(x::Cell) = unique(map(gdslayer, x.element_metadata))
+
+"""
+    gdslayers(x::GeometryStructure)
+
+Returns the unique GDS layers of elements in `x`, using [`DeviceLayout.default_meta_map`](@ref). Does *not* return the layers
+in referenced structures.
+"""
+gdslayers(x::GeometryStructure) =
+    unique(map(gdslayer ∘ DeviceLayout.default_meta_map, element_metadata(x)))
 layers(x::Cell) = unique(map(gdslayer, x.element_metadata))
 
+@deprecate layers(x) gdslayers(x)
+
 """
     text!(c::Cell{S}, str::String, origin::Point=zero(Point{S}), meta::Meta=GDSMeta(); kwargs...) where {S}
 
@@ -267,8 +279,7 @@ function text!(
     meta::GDSMeta=GDSMeta();
     kwargs...
 ) where {S}
-    push!(c.texts, Texts.Text(; text, origin, kwargs...))
-    return push!(c.text_metadata, meta)
+    return text!(c, Texts.Text(; text, origin, kwargs...), meta)
 end
 
 function text!(
@@ -278,8 +289,7 @@ function text!(
     origin=zero(Point{S}),
     kwargs...
 ) where {S}
-    push!(c.texts, Texts.Text(; text, origin, kwargs...))
-    return push!(c.text_metadata, meta)
+    return text!(c, Texts.Text(; text, origin, kwargs...), meta)
 end
 
 """
@@ -289,12 +299,14 @@ Annotate cell `c` with `Texts.Text` object.
 """
 function text!(c::Cell, text::Texts.Text, meta)
     push!(c.texts, text)
-    return push!(c.text_metadata, meta)
+    push!(c.text_metadata, meta)
+    return c
 end
 
 function text!(c::Cell{S}, texts::Vector{Texts.Text{S}}, meta::Vector{GDSMeta}) where {S}
     append!(c.texts, texts)
-    return append!(c.text_metadata, meta)
+    append!(c.text_metadata, meta)
+    return c
 end
 
 Base.isempty(c::Cell) = isempty(elements(c)) && isempty(refs(c)) && isempty(c.texts)

src/coordinate_systems.jl

@@ -135,14 +135,16 @@ Place `ent` in `cs` with metadata `metadata`.
 """
 function place!(cs::CoordinateSystem, ent::GeometryEntity, metadata::Meta)
     push!(cs.elements, ent)
-    return push!(cs.element_metadata, metadata)
+    push!(cs.element_metadata, metadata)
+    return cs
 end
 place!(cs::CoordinateSystem, geom, layer::Union{Symbol, String}) =
     place!(cs, geom, SemanticMeta(layer))
 
 function place!(cs::CoordinateSystem, ents::Vector, metadata::Vector{<:Meta})
     append!(cs.elements, ents)
-    return append!(cs.element_metadata, metadata)
+    append!(cs.element_metadata, metadata)
+    return cs
 end
 
 """
@@ -151,7 +153,8 @@ end
 Place a reference to `s` in `cs`.
 """
 function place!(cs::CoordinateSystem, s::GeometryStructure)
-    return addref!(cs, s)
+    addref!(cs, s)
+    return cs
 end
 
 """

src/metadata.jl

@@ -10,13 +10,18 @@
 DeviceLayout-native representation of an object's layer information and attributes.
 
 Semantic metadata refers to the meaning of an element without reference to a fixed encoding.
-For example, “this polygon is in the negative of the ground plane” is semantic, while
-“this polygon is in GDS layer 1, datatype 2” is not. The semantic metadata is used in the
+For example, "this polygon is in the negative of the ground plane" is semantic, while
+"this polygon is in GDS layer 1, datatype 2" is not. The semantic metadata is used in the
 final `render` step, where a layout is converted from a `CoordinateSystem` to a
 representation corresponding to a particular output format (e.g., a `Cell` for GDSII).
-A call to `render!(cell::Cell{S}, cs::CoordinateSystem; map_meta = identity, kwargs...)`
+A call to `render!(cell::Cell{S}, cs::CoordinateSystem; map_meta = default_meta_map, kwargs...)`
 will use the `map_meta` function to map each `GeometryEntity`'s metadata to `GDSMeta`.
 
+By default, [`DeviceLayout.default_meta_map`](@ref) is used, which:
+
+  - Passes GDSMeta through unchanged
+  - Converts other metadata types to GDSMeta using a hash-based layer assignment (0-255)
+
 The `level` and `index` fields do not have a strict interpretation imposed by DeviceLayout. (In
 this sense they are similar to GDS `datatype`.) The suggested use is as follows:
 
@@ -142,3 +147,53 @@ layer_inclusion(only_layers, ignore_layers::Union{Symbol, Meta}) =
     layer_inclusion(only_layers, [ignore_layers])
 layer_inclusion(only_layers::Union{Symbol, Meta}, ignore_layers::Union{Symbol, Meta}) =
     layer_inclusion([only_layers], [ignore_layers])
+
+"""
+    hash_to_gdslayer(meta::Meta) -> Int
+
+Convert metadata `m` to a GDS layer number (0-255) by hashing `(layer(m), level(m))`.
+
+Values are repeatable for different metadata, but only probably distinct.
+"""
+function hash_to_gdslayer(meta::Meta)
+    h = hash((layer(meta), level(meta)))
+    return Int(h % UInt8)
+end
+
+"""
+    default_meta_map(meta::Meta) -> GDSMeta
+
+Default metadata mapping function for rendering to Cell.
+
+This map is for convenient graphical display and should not be relied on in production workflows.
+
+GDSMeta passes through unchanged.
+
+Other Meta types are converted to GDSMeta using a
+layer in (0-255) based on the hash of `(layer(m), level(m))` and datatype
+`layerindex(m)-1` (clamped to 0-255). This means that other metadata
+types are not guaranteed to be mapped to unique GDSMeta.
+
+# Examples
+
+```julia
+julia> default_meta_map(GDSMeta(10, 2))
+GDSMeta(10, 2)
+
+julia> default_meta_map(SemanticMeta(:metal))
+GDSMeta(63, 0)  # Hash-based layer, datatype from index
+
+julia> default_meta_map(SemanticMeta(:metal, index=5))
+GDSMeta(63, 4)  # Same layer, different datatype
+```
+"""
+function default_meta_map(meta::GDSMeta)
+    return meta
+end
+
+function default_meta_map(meta::Meta)
+    layer_num = hash_to_gdslayer(meta)
+    # Use layerindex-1 as datatype (0-based), clamped to valid range
+    datatype_num = clamp(layerindex(meta) - 1, 0, 255)
+    return GDSMeta(layer_num, datatype_num)
+end