EzyCad settings

This guide covers the Settings pane (what is on screen), the View menu (pane visibility is separate from Settings), where preferences are saved, the startup project, and the JSON settings schema (some keys are not edited in the Settings pane). For the rest of the application, see the main usage guide.

View menu

View toggles panes and opens Settings:

Settings - Opens the Settings pane.
Options - Show or hide the Options panel.
Sketch List - Show or hide the Sketch List pane.
Shape List - Show or hide the Shape List pane.
Log - Show or hide the Log window.
Lua Console - Show or hide the interactive Lua prompt and res/scripts/lua editors. See Scripting.
Python Console - Same for Python when the app is built with embedded Python (native only; not in the WebAssembly build).
Debug - Show or hide the debug pane (debug builds only).

Visibility of these panes (and related flags) is persisted with the rest of your settings.

Help menu

About - Opens the project README in the browser.
Usage Guide - Opens the online usage guide (Read the Docs).

Settings pane

Open View -> Settings. The window title is Settings.

Dark mode — checkbox at the top (not inside a collapsible section).
At the bottom: Defaults — reloads bundled defaults from the app res/ tree (including ImGui layout from that file).

Between those, the pane has six collapsible sections. Expand a section to see its controls; when collapsed, only the section title bar is visible.

3D view navigation — View rotation step (degrees per key press for NumPad 8/2/4/6 orbit and Shift+NumPad 4/6 roll; default 45; ? opens view roll on Read the Docs). Zoom scroll scale (multiplier for wheel and +/- zoom; default 4). Hold Shift while zooming for a Blender-style finer step (multiply by 0.1). Numpad shortcuts are documented with Num Lock off; with Num Lock on, use main-row alternatives in usage.md -> View navigation. Stored as gui.view_roll_step_deg and gui.view_zoom_scroll_scale. See usage-occt-view.md.
UI corner rounding — Sliders 0 to 16 for Windows, frames, popups; Scrollbars and sliders (has (?)); Tabs.
3D view background — Background color 1 and Background color 2 (float RGB fields and swatches). Gradient blend — combo: Horizontal, Vertical, Diagonal 1, Diagonal 2, Corner 1 … Corner 4.
3D view grid — Fine grid lines and Major grid lines (passed to Open CASCADE Aspect_Grid::SetColors: dense lines vs every-tenth emphasis lines). Grid step, Grid extent X / Y (full span edge-to-edge), and Grid display Z offset in the Settings pane use the same length scale as sketch length dimensions (display value = model value / internal dimension_scale, default 100). Saved JSON (occt_view) stores half-extent in model units for OCCT (grid_graphic_*); Settings shows full extent (twice the stored half-extent).
Sketch — Expand Dimensions (nested, open by default) for length-dimension appearance and behavior (most rows have (?) tooltips). Other sketch rows stay in the parent Sketch section:
- Dimension line width — slider 0.5 to 8.0
- Dimension arrow size — slider 1.0 to 24.0
- Dimension color — RGB for dimension lines, arrow heads, and value text
- Dimension text scale — slider 0.5 to 3.0 (multiplier on label height)
- Label rendering — Opaque 2D text, SetCommonColor, 2D screen text, 3D text, Z-layer Top, Z-layer Topmost (default)
- Length value placement — combo: Near first point, Near second point, Center on dimension line, Automatic (persisted as edge_dim_label_h 0–3; updates existing dimensions live)
- Arrow style — Standard, Sharp, Wide, or 3D shaded
- Arrow orientation — Automatic, Internal, or External
- Show sketch dimensions — global on/off for length dimensions on all sketches (tool mode may still limit which sketch shows dims when on)
- Permanent node annotation size, Underlay highlight color, Snap guide color, Snap guide mode (directly under Sketch, not inside Dimensions)
Startup project — Desktop only: Load last opened on startup (checkbox, with (?)), then Last opened path: … or (No path saved yet.) Then Save current as startup project, Clear saved startup (with (?)). WebAssembly: no load-last row; only the two buttons and (?). See Startup project.

Not in this pane

View menu items such as Options, Sketch List, Lua Console — they only show or hide panes; they are not rows inside Settings. Their visibility is still saved under gui.* in the settings file (see Settings file reference). Saving — On desktop, settings are written when you change options that save, and on exit. On Emscripten, use File -> Save settings so the browser persists (see Where settings are stored).

Options panel

Open View -> Options. Content depends on the active tool mode. Related controls are grouped under headings (for example Sketch options, Extrude, Selection, Material).

If you resize the pane narrower than its controls, a horizontal scrollbar appears so long labels (for example Orthographic projection) stay readable.

Normal mode (Inspection)

Under Selection:

Selection Mode — combo for the 3D pick filter (vertices, edges, faces, solids, and combinations). The (?) marker links to shape selection filter hotkeys in the usage guide.
Orthographic projection — checkbox toggling an orthographic camera in inspection mode (sketch modes still force orthographic as before). Persisted as gui.inspection_orthographic.

Under Material:

Document preset for new solids that do not inherit from a clicked shape (toolbar Box, polar duplicate output, and similar). To change material on an existing solid, use the Shape List.

For other non-sketch Options content (for example Polar duplicate), see usage.md -> User Interface (Options Panel).

Sketch tools

Sketch-related preferences are edited in the Options panel while you use a sketch tool, not in the Settings pane:

Sketch options (all sketch tools): Snap dist and Snap guide mode (Traditional, Fullscreen, Both). See How sketch snap works in the sketch guide (axis guides, vertex lock, cross-sketch targets). Snap guide color and mode are also in Settings -> Sketch.
Extrude sketch face: under Extrude, Both sides and Material for the new solid (same document preset as Normal mode Options Material). Other modes that still show Material in Options use that same preset when relevant (for example Sketch from planar face).
Add edge / Add node (and similar): a Shortcuts line documents TAB / Shift+TAB typing behavior.
Sketch operation (mirror / revolve axis): mirror, revolve, angle, and clear-axis actions (see usage-sketch.md).

Global length-dimension style (line width, arrows, color, text) is in Settings -> Sketch. Per-dimension visibility, name, and offset remain in Sketch List -> Dimensions (saved in the project .ezy file).

Where settings are stored

EzyCad reads and writes a single JSON file named ezycad_settings.json.

Windows — %APPDATA%\EzyCad\
Linux — ~/.config/EzyCad/
macOS — ~/Library/Application Support/EzyCad/

If the user-specific file is missing, the app may fall back to a legacy copy in the current working directory (next to the executable when launched that way).

WebAssembly — Settings are kept in the browser under the localStorage key ezycad_settings. Use File -> Save settings to persist after changes.

Bundled defaults for Defaults and first-run live under the res/ folder in the install or build output (same basename as above).

Startup project

Similar to Blender’s startup file: EzyCad can load a default document when it starts, including geometry, camera/view (stored in the .ezy), and current tool mode.

First launch / no custom startup - The app loads the bundled template res/default.ezy from the install or build output.
Save your own startup - Set up the scene and mode the way you want, open Settings, expand Startup project, and click Save current as startup project. On desktop, this writes startup.ezy under your user config folder (same base paths as above). On the web build, it is stored in the browser (localStorage).
Next runs - If a saved startup exists, it is loaded instead of the bundled file. The session starts untitled (so Save does not overwrite your startup file until you pick a path).
Clear saved startup - In Settings -> Startup project, click Clear saved startup; the next launch uses the bundled res/default.ezy again.

Settings file reference

The on-disk (or localStorage) document is JSON with a version, optional ImGui layout blob, an occt_view object for the 3D view, and a gui object. gui includes pane visibility and other flags that are not all exposed as controls in the Settings pane (for example show sketch list comes from View, not from a row inside Settings).

`version`

String "1". If the version is missing or does not match, the app replaces the file with bundled defaults (see gui_settings.cpp).

`imgui_ini`

String: ImGui .ini text for window positions and docking saved with SaveIniSettingsToMemory. Loaded with LoadIniSettingsFromMemory on startup.

`occt_view`

Key	Type	Meaning
`bg_color1`	array of 3 numbers	Background gradient color 1 (float RGB, 0 to 1).
`bg_color2`	array of 3 numbers	Background gradient color 2.
`bg_gradient_method`	integer	Gradient mode: 0 horizontal, 1 vertical, 2 to 3 diagonals, 4 to 7 corners (same order as the Settings pane combo).
`grid_color1`	array of 3 numbers	Fine (dense) grid lines (`Aspect_Grid` main color).
`grid_color2`	array of 3 numbers	Major (sparse / every-tenth) grid lines (`Aspect_Grid` tenth-line color).
`grid_step`	number	Grid line spacing in model units (`Aspect_RectangularGrid`; default 10). Legacy `grid_x_step` / `grid_y_step` load as this value (X preferred).
`grid_graphic_x_size`	number	Grid half-extent on X in model units (OCCT `SetGraphicValues`; default 1000). Settings Grid extent X shows full span (20 with those defaults).
`grid_graphic_y_size`	number	Grid half-extent on Y in model units. Settings Grid extent Y shows full span.
`grid_graphic_z_offset`	number	Grid plane offset along Z in model units.

`gui`

Key	Type	Meaning
`dark_mode`	boolean	Light/dark theme.
`show_options`	boolean	Options panel visible.
`show_sketch_list`	boolean	Sketch List pane visible.
`show_shape_list`	boolean	Shape List pane visible.
`log_window_visible`	boolean	Log window visible.
`show_settings_dialog`	boolean	Whether the Settings pane was open when last saved (usually false).
`show_lua_console`	boolean	Lua console pane visible.
`show_python_console`	boolean	Python console pane visible (native builds with Python).
`show_dbg`	boolean	Debug pane visible (debug builds only).
`inspection_orthographic`	boolean	Normal mode Options: orthographic camera when true (default false).
`edge_dim_label_h`	integer	Length dimension label placement: 0 near first point, 1 near second, 2 center, 3 automatic.
`edge_dim_line_width`	number	Sketch length dimension line width (0.5 to 8.0).
`edge_dim_arrow_size`	number	Arrow head length (1.0 to 24.0).
`edge_dim_color`	array of 3 numbers	Dimension line, arrow, and text RGB (0 to 1 per channel; default yellow).
`edge_dim_text_scale`	number	Label height multiplier (0.5 to 3.0; default 1.0).
`edge_dim_text_render_mode`	integer	0 opaque 2D, 1 SetCommonColor, 2 2D screen, 3 3D text, 4 Z Top, 5 Z Topmost (default).
`edge_dim_arrow_style`	integer	0 standard, 1 sharp, 2 wide, 3 3D shaded.
`edge_dim_arrow_orientation`	integer	0 automatic, 1 internal, 2 external.
`show_sketch_dimensions`	boolean	When false, hides length dimensions on all sketches.
`imgui_rounding_general`	number	Window/child/frame/popup rounding (0 to 32 clamped in code; sliders stop at 16 in the UI).
`imgui_rounding_scroll`	number	Scrollbar and grab rounding (same clamp).
`imgui_rounding_tabs`	number	Tab rounding (same clamp).
`underlay_highlight_color`	array of 3 numbers	Default underlay tint (float RGB 0 to 1 per channel).
`view_roll_step_deg`	number	Degrees per NumPad 8/2/4/6 orbit and Shift+NumPad 4/6 roll (allowed range 0.1 to 180 in code; default 45).
`view_zoom_scroll_scale`	number	Multiplier for `UpdateZoom` scroll delta from wheel and keyboard zoom (allowed range 0.25 to 64 in code; default 4). With Shift held, the effective step is multiplied by 0.1 (Blender-style finer zoom).
`load_last_opened_on_startup`	boolean	Desktop: open the last `.ezy` on launch. Legacy: `load_last_saved_on_startup` is read as a fallback if the newer key is absent.
`last_opened_project_path`	string	Path of the last opened project for the option above. Legacy: `last_saved_project_path` is accepted if the newer key is missing.

Scripting API ezy.occt_view_settings_json() returns a JSON string with occt_view plus selected gui keys (including dimension keys above, gui.inspection_orthographic, gui.view_roll_step_deg, gui.view_zoom_scroll_scale when saved). See scripting.md.

For general workflows and tools, see usage.md. For the 3D viewer (Open CASCADE), see usage-occt-view.md. For 2D sketching, see usage-sketch.md.