pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/GetSchedules.cs

@@ -1,89 +1,96 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class GetSchedules : ITool
-{
-    public string Name => "get_schedules";
-    public string Label => "Get Schedules";
-    public string Tier => "advanced";
-    public string Description => "List schedules, or read one schedule's field definitions and displayed body cells by schedule_id. Cell text uses Revit formatting and may contain group headings/totals; rows are not guaranteed to correspond to individual elements. Row and column pagination are independent. Templates and revision schedules are excluded from the list.";
-    public object ParametersSchema => new
-    {
-        type = "object",
-        properties = new
-        {
-            schedule_id = new { type = "integer" },
-            name_filter = new { type = "string" },
-            offset = new { type = "integer", minimum = 0, description = "List offset or body row offset." },
-            limit = new { type = "integer", minimum = 1, maximum = 200 },
-            column_offset = new { type = "integer", minimum = 0 },
-            column_limit = new { type = "integer", minimum = 1, maximum = 50 },
-        },
-        required = Array.Empty<string>(),
-    };
-
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
-        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 50), 1, 200);
-        if (JsonArgs.GetLong(args, "schedule_id") is not { } id)
-        {
-            string needle = JsonArgs.GetString(args, "name_filter") ?? "";
-            var schedules = new FilteredElementCollector(doc).OfClass(typeof(ViewSchedule)).Cast<ViewSchedule>()
-                .Where(s => !s.IsTemplate && !s.IsTitleblockRevisionSchedule && s.Name.Contains(needle, StringComparison.OrdinalIgnoreCase))
-                .OrderBy(s => s.Id.Value).ToList();
-            var rows = schedules.Skip(offset).Take(limit).Select(s => new
-            {
-                id = s.Id.Value, name = s.Name, unique_id = s.UniqueId,
-                category_id = s.Definition.CategoryId.Value,
-                is_itemized = s.Definition.IsItemized,
-                field_count = s.Definition.GetFieldCount(),
-            }).ToArray();
-            return new { total_count = schedules.Count, returned_count = rows.Length, offset,
-                has_more = offset + rows.Length < schedules.Count,
-                next_offset = offset + rows.Length < schedules.Count ? (int?)(offset + rows.Length) : null, schedules = rows };
-        }
-
-        var schedule = doc.GetElement(new ElementId(id)) as ViewSchedule
-            ?? throw new ArgumentException("schedule_id is not a schedule in the active document.");
-        if (schedule.IsTemplate) throw new ArgumentException("Schedule templates do not contain displayed body rows.");
-        using var table = schedule.GetTableData();
-        using var body = table.GetSectionData(SectionType.Body);
-        int columnOffset = Math.Max(0, JsonArgs.GetInt(args, "column_offset", 0));
-        int columnLimit = Math.Clamp(JsonArgs.GetInt(args, "column_limit", 50), 1, 50);
-        int columnCount = Math.Min(columnLimit, Math.Max(0, body.NumberOfColumns - columnOffset));
-        int rowCount = Math.Min(limit, Math.Max(0, body.NumberOfRows - offset));
-        var cells = Enumerable.Range(0, rowCount).Select(row => new
-        {
-            row_index = body.FirstRowNumber + offset + row,
-            cells = Enumerable.Range(0, columnCount).Select(col => schedule.GetCellText(SectionType.Body,
-                body.FirstRowNumber + offset + row, body.FirstColumnNumber + columnOffset + col)).ToArray(),
-        }).ToArray();
-        var fields = schedule.Definition.GetFieldOrder().Select(fieldId =>
-        {
-            var field = schedule.Definition.GetField(fieldId);
-            return new { field_id = fieldId.IntegerValue, parameter_id = field.ParameterId.Value,
-                name = field.GetName(), heading = field.ColumnHeading, hidden = field.IsHidden, field_type = field.FieldType.ToString(),
-                spec_type_id = field.GetSpecTypeId().TypeId, grid_width_feet = field.GridColumnWidth, sheet_width_feet = field.SheetColumnWidth,
-                can_filter_value = schedule.Definition.CanFilterByValue(fieldId), can_filter_substring = schedule.Definition.CanFilterBySubstring(fieldId) };
-        }).ToArray();
-        return new
-        {
-            schedule_id = id, name = schedule.Name, is_itemized = schedule.Definition.IsItemized, fields,
-            sort_fields = schedule.Definition.GetSortGroupFields().Select(sort => new { field_id = sort.FieldId.IntegerValue, order = sort.SortOrder.ToString(), show_header = sort.ShowHeader }).ToArray(),
-            filters = schedule.Definition.GetFilters().Select(filter => new { field_id = filter.FieldId.IntegerValue, comparison = filter.FilterType.ToString(),
-                value = filter.IsStringValue ? (object)filter.GetStringValue() : filter.IsDoubleValue ? filter.GetDoubleValue() : filter.IsIntegerValue ? filter.GetIntegerValue() : filter.IsElementIdValue ? filter.GetElementIdValue().Value : null,
-                value_unit = filter.IsDoubleValue ? "internal" : null }).ToArray(),
-            total_rows = body.NumberOfRows, total_columns = body.NumberOfColumns,
-            offset, returned_rows = rowCount,
-            next_offset = offset + rowCount < body.NumberOfRows ? (int?)(offset + rowCount) : null,
-            column_offset = columnOffset, returned_columns = columnCount,
-            first_column_index = body.FirstColumnNumber + columnOffset,
-            next_column_offset = columnOffset + columnCount < body.NumberOfColumns ? (int?)(columnOffset + columnCount) : null,
-            rows = cells,
-        };
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class GetSchedules : ITool
+{
+    public string Name => "get_schedules";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "schedule", "quantities", "takeoff", "table", "schedule cells", "schedule values", "bill of quantities" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Titleblock revision schedules and schedule templates", "api", "ViewSchedule.IsTitleblockRevisionSchedule; ViewSchedule.GetTableData"),
+        new ToolLimit("Graphical layout of a schedule on a sheet", "tool", "capture_view"),
+    };
+    public string Label => "Get Schedules";
+    public string Tier => "advanced";
+    public string Description => "List schedules, or read one schedule's field definitions and displayed body cells by schedule_id. Cell text uses Revit formatting and may contain group headings/totals; rows are not guaranteed to correspond to individual elements. Row and column pagination are independent. Templates and revision schedules are excluded from the list.";
+    public object ParametersSchema => new
+    {
+        type = "object",
+        properties = new
+        {
+            schedule_id = new { type = "integer" },
+            name_filter = new { type = "string" },
+            offset = new { type = "integer", minimum = 0, description = "List offset or body row offset." },
+            limit = new { type = "integer", minimum = 1, maximum = 200 },
+            column_offset = new { type = "integer", minimum = 0 },
+            column_limit = new { type = "integer", minimum = 1, maximum = 50 },
+        },
+        required = Array.Empty<string>(),
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 50), 1, 200);
+        if (JsonArgs.GetLong(args, "schedule_id") is not { } id)
+        {
+            string needle = JsonArgs.GetString(args, "name_filter") ?? "";
+            var schedules = new FilteredElementCollector(doc).OfClass(typeof(ViewSchedule)).Cast<ViewSchedule>()
+                .Where(s => !s.IsTemplate && !s.IsTitleblockRevisionSchedule && s.Name.Contains(needle, StringComparison.OrdinalIgnoreCase))
+                .OrderBy(s => s.Id.Value).ToList();
+            var rows = schedules.Skip(offset).Take(limit).Select(s => new
+            {
+                id = s.Id.Value, name = s.Name, unique_id = s.UniqueId,
+                category_id = s.Definition.CategoryId.Value,
+                is_itemized = s.Definition.IsItemized,
+                field_count = s.Definition.GetFieldCount(),
+            }).ToArray();
+            return new { total_count = schedules.Count, returned_count = rows.Length, offset,
+                has_more = offset + rows.Length < schedules.Count,
+                next_offset = offset + rows.Length < schedules.Count ? (int?)(offset + rows.Length) : null, schedules = rows };
+        }
+
+        var schedule = doc.GetElement(new ElementId(id)) as ViewSchedule
+            ?? throw new ArgumentException("schedule_id is not a schedule in the active document.");
+        if (schedule.IsTemplate) throw new ArgumentException("Schedule templates do not contain displayed body rows.");
+        using var table = schedule.GetTableData();
+        using var body = table.GetSectionData(SectionType.Body);
+        int columnOffset = Math.Max(0, JsonArgs.GetInt(args, "column_offset", 0));
+        int columnLimit = Math.Clamp(JsonArgs.GetInt(args, "column_limit", 50), 1, 50);
+        int columnCount = Math.Min(columnLimit, Math.Max(0, body.NumberOfColumns - columnOffset));
+        int rowCount = Math.Min(limit, Math.Max(0, body.NumberOfRows - offset));
+        var cells = Enumerable.Range(0, rowCount).Select(row => new
+        {
+            row_index = body.FirstRowNumber + offset + row,
+            cells = Enumerable.Range(0, columnCount).Select(col => schedule.GetCellText(SectionType.Body,
+                body.FirstRowNumber + offset + row, body.FirstColumnNumber + columnOffset + col)).ToArray(),
+        }).ToArray();
+        var fields = schedule.Definition.GetFieldOrder().Select(fieldId =>
+        {
+            var field = schedule.Definition.GetField(fieldId);
+            return new { field_id = fieldId.IntegerValue, parameter_id = field.ParameterId.Value,
+                name = field.GetName(), heading = field.ColumnHeading, hidden = field.IsHidden, field_type = field.FieldType.ToString(),
+                spec_type_id = field.GetSpecTypeId().TypeId, grid_width_feet = field.GridColumnWidth, sheet_width_feet = field.SheetColumnWidth,
+                can_filter_value = schedule.Definition.CanFilterByValue(fieldId), can_filter_substring = schedule.Definition.CanFilterBySubstring(fieldId) };
+        }).ToArray();
+        return new
+        {
+            schedule_id = id, name = schedule.Name, is_itemized = schedule.Definition.IsItemized, fields,
+            sort_fields = schedule.Definition.GetSortGroupFields().Select(sort => new { field_id = sort.FieldId.IntegerValue, order = sort.SortOrder.ToString(), show_header = sort.ShowHeader }).ToArray(),
+            filters = schedule.Definition.GetFilters().Select(filter => new { field_id = filter.FieldId.IntegerValue, comparison = filter.FilterType.ToString(),
+                value = filter.IsStringValue ? (object)filter.GetStringValue() : filter.IsDoubleValue ? filter.GetDoubleValue() : filter.IsIntegerValue ? filter.GetIntegerValue() : filter.IsElementIdValue ? filter.GetElementIdValue().Value : null,
+                value_unit = filter.IsDoubleValue ? "internal" : null }).ToArray(),
+            total_rows = body.NumberOfRows, total_columns = body.NumberOfColumns,
+            offset, returned_rows = rowCount,
+            next_offset = offset + rowCount < body.NumberOfRows ? (int?)(offset + rowCount) : null,
+            column_offset = columnOffset, returned_columns = columnCount,
+            first_column_index = body.FirstColumnNumber + columnOffset,
+            next_column_offset = columnOffset + columnCount < body.NumberOfColumns ? (int?)(columnOffset + columnCount) : null,
+            rows = cells,
+        };
+    }
+}

package/src/Revit/Tools/InheritedState.Summary.cs

@@ -0,0 +1,57 @@
+namespace RevitBridge.Tools
+{
+    /// <summary>The Revit-free part of InheritedState: limits, the facts record and the summary. Tested offline.</summary>
+    internal static partial class InheritedState
+    {
+        public const int ListCap = 30;
+        public const int SampleCap = 10;
+        public static readonly TimeSpan ScanBudget = TimeSpan.FromSeconds(4);
+
+        public const string ViewCheck = "Inherited from the source view. Compare this state with the request: show anything the request asks to show, or disclose what stays hidden, and report what was inherited.";
+        public const string NewViewCheck = "A new view starts with this visibility state; a duplicate inherits its source's state. Compare it with the request before reporting the view as complete.";
+        public const string ElementCheck = "Carried over from the source object. Check these values against the request; a copied Mark or Comment usually needs a new value.";
+
+        /// <summary>Facts read from one view. Lists hold category identities as "OST_Name|Localized name".</summary>
+        internal sealed record ViewFacts(
+            long? SourceId, long? TemplateId, string? TemplateName,
+            IReadOnlyList<string> HiddenCategories, int HiddenElementCount, IReadOnlyList<long> HiddenElementSample,
+            int ElementOverrideCount, bool ElementScanComplete, int CategoryOverrideCount,
+            IReadOnlyList<(long Id, string Name, bool Visible)> Filters, bool TemporaryHideIsolate,
+            string? DisplayStyle, string? DetailLevel, bool CropActive, bool? SectionBoxActive, bool? Perspective);
+
+        /// <summary>Pure summary of view facts: only non-empty sections, capped lists, and the check the caller must make.</summary>
+        public static Dictionary<string, object?> Summarize(ViewFacts facts, string check)
+        {
+            var state = new Dictionary<string, object?>();
+            if (facts.SourceId is long source) state["derived_from"] = source;
+            if (facts.TemplateId is long template && template > 0) state["template"] = new Dictionary<string, object?> { ["id"] = template, ["name"] = facts.TemplateName };
+            if (facts.HiddenCategories.Count > 0)
+                state["hidden_categories"] = new Dictionary<string, object?>
+                {
+                    ["count"] = facts.HiddenCategories.Count,
+                    ["categories"] = facts.HiddenCategories.Take(ListCap).ToList(),
+                    ["truncated"] = facts.HiddenCategories.Count > ListCap,
+                };
+            if (facts.HiddenElementCount > 0 || !facts.ElementScanComplete)
+                state["hidden_elements"] = new Dictionary<string, object?>
+                {
+                    ["count"] = facts.HiddenElementCount,
+                    ["sample_ids"] = facts.HiddenElementSample.Take(SampleCap).ToList(),
+                    ["complete"] = facts.ElementScanComplete,
+                };
+            if (facts.ElementOverrideCount > 0) state["element_overrides"] = facts.ElementOverrideCount;
+            if (facts.CategoryOverrideCount > 0) state["category_overrides"] = facts.CategoryOverrideCount;
+            if (facts.Filters.Count > 0)
+                state["filters"] = facts.Filters.Take(ListCap).Select(f => new Dictionary<string, object?> { ["id"] = f.Id, ["name"] = f.Name, ["visible"] = f.Visible }).ToList();
+            if (facts.TemporaryHideIsolate) state["temporary_hide_isolate"] = true;
+            var display = new Dictionary<string, object?> { ["display_style"] = facts.DisplayStyle, ["detail_level"] = facts.DetailLevel, ["crop_box_active"] = facts.CropActive };
+            if (facts.SectionBoxActive is bool box) display["section_box_active"] = box;
+            if (facts.Perspective is bool perspective) display["perspective"] = perspective;
+            state["display"] = display;
+            if (!facts.ElementScanComplete)
+                state["scan_note"] = $"The hidden-element scan stopped after {ScanBudget.TotalSeconds:0} s; counts are lower bounds.";
+            state["check"] = check;
+            return state;
+        }
+    }
+}

package/src/Revit/Tools/InheritedState.cs

@@ -0,0 +1,144 @@
+using System.Diagnostics;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Shared report of the state an object carries when it is derived from an existing one
+    /// (inv:derived-state-reported). A duplicated view keeps its source's hidden categories and
+    /// elements, filters, overrides and template; a copied element keeps its instance values; a
+    /// retyped element keeps its per-view graphics. Any tool that duplicates, copies, mirrors or
+    /// retypes reports this in its result, so the caller can compare it with the request instead
+    /// of relying on an image. The gate in scripts/check-tool-documentation.mjs makes every tool
+    /// that creates from an existing object use this class. Reading and summarizing are separate:
+    /// Summarize is pure and tested offline; the Read* methods only collect facts from Revit.
+    /// </summary>
+    internal static partial class InheritedState
+    {
+        /// <summary>Inherited state of a view derived from source (null when unknown), for a result.</summary>
+        public static Dictionary<string, object?> OfView(View view, long? sourceId, string check = ViewCheck)
+            => Summarize(ReadView(view, sourceId), check);
+
+        /// <summary>Collect facts from Revit. The element scan is bounded by ScanBudget.</summary>
+        public static ViewFacts ReadView(View view, long? sourceId)
+        {
+            var doc = view.Document;
+            var hiddenCategories = new List<string>();
+            int categoryOverrides = 0;
+            foreach (Category category in doc.Settings.Categories)
+            {
+                try
+                {
+                    if (view.CanCategoryBeHidden(category.Id) && view.GetCategoryHidden(category.Id))
+                        hiddenCategories.Add($"{category.BuiltInCategory}|{category.Name}");
+                    if (view.AreGraphicsOverridesAllowed() && view.IsCategoryOverridable(category.Id) && IsNonDefault(view.GetCategoryOverrides(category.Id)))
+                        categoryOverrides++;
+                }
+                catch (Autodesk.Revit.Exceptions.ArgumentException) { }
+            }
+
+            int hidden = 0, overridden = 0;
+            var sample = new List<long>();
+            bool complete = true;
+            var clock = Stopwatch.StartNew();
+            var candidates = new FilteredElementCollector(doc).WhereElementIsNotElementType().WhereElementIsViewIndependent()
+                .Concat(new FilteredElementCollector(doc).OwnedByView(view.Id));
+            foreach (var element in candidates)
+            {
+                if (clock.Elapsed > ScanBudget) { complete = false; break; }
+                try
+                {
+                    if (element.CanBeHidden(view) && element.IsHidden(view))
+                    {
+                        hidden++;
+                        if (sample.Count < SampleCap) sample.Add(element.Id.Value);
+                    }
+                    if (view.AreGraphicsOverridesAllowed() && IsNonDefault(view.GetElementOverrides(element.Id))) overridden++;
+                }
+                catch (Autodesk.Revit.Exceptions.ArgumentException) { }
+                catch (Autodesk.Revit.Exceptions.InvalidOperationException) { }
+            }
+
+            var filters = new List<(long, string, bool)>();
+            try
+            {
+                foreach (var id in view.GetFilters())
+                    filters.Add((id.Value, doc.GetElement(id)?.Name ?? "", view.GetFilterVisibility(id)));
+            }
+            catch (Autodesk.Revit.Exceptions.InvalidOperationException) { }
+
+            var template = view.ViewTemplateId;
+            var view3D = view as View3D;
+            return new ViewFacts(sourceId, template.Value > 0 ? template.Value : null, template.Value > 0 ? doc.GetElement(template)?.Name : null,
+                hiddenCategories, hidden, sample, overridden, complete, categoryOverrides, filters, Safe(() => view.IsTemporaryHideIsolateActive()),
+                Safe(() => view.DisplayStyle.ToString()), Safe(() => view.DetailLevel.ToString()), Safe(() => view.CropBoxActive),
+                view3D == null ? null : Safe(() => view3D.IsSectionBoxActive), view3D?.IsPerspective);
+        }
+
+        /// <summary>Some view kinds (schedules, sheets) reject graphics properties; report them as unset.</summary>
+        private static T? Safe<T>(Func<T> read)
+        {
+            try { return read(); }
+            catch (Autodesk.Revit.Exceptions.InvalidOperationException) { return default; }
+            catch (Autodesk.Revit.Exceptions.ArgumentException) { return default; }
+        }
+
+        /// <summary>True when an override changes anything from the view's normal graphics.</summary>
+        public static bool IsNonDefault(OverrideGraphicSettings o) =>
+            o.Halftone || o.Transparency != 0 || o.DetailLevel != ViewDetailLevel.Undefined
+            || o.ProjectionLineColor.IsValid || o.ProjectionLineWeight != OverrideGraphicSettings.InvalidPenNumber
+            || o.CutLineColor.IsValid || o.CutLineWeight != OverrideGraphicSettings.InvalidPenNumber
+            || o.SurfaceForegroundPatternId != ElementId.InvalidElementId || o.CutForegroundPatternId != ElementId.InvalidElementId
+            || !o.IsSurfaceForegroundPatternVisible || !o.IsCutForegroundPatternVisible;
+
+        /// <summary>
+        /// Inherited state of an element derived from source: its special traits, identity-like
+        /// values that were copied (Mark, Comments), and views that hide or override it (bounded).
+        /// Per-view hiding and overrides are keyed by element ID, so a copy (new ID) never inherits
+        /// them; pass viewGraphics only when the element keeps its ID, as a retyped element does.
+        /// Views get the view report instead. Returns null when nothing was carried over.
+        /// </summary>
+        public static Dictionary<string, object?>? OfElement(Element derived, long? sourceId, bool viewGraphics = false)
+        {
+            if (derived is View view) return OfView(view, sourceId);
+            var state = new Dictionary<string, object?>();
+            if (sourceId is long source && source != derived.Id.Value) state["derived_from"] = source;
+            if (ElementTraits.For(derived) is { } traits) state["traits"] = traits;
+            var carried = new Dictionary<string, object?>();
+            foreach (var (key, parameter) in new[] { ("mark", BuiltInParameter.ALL_MODEL_MARK), ("comments", BuiltInParameter.ALL_MODEL_INSTANCE_COMMENTS) })
+                if (derived.get_Parameter(parameter)?.AsString() is { Length: > 0 } value) carried[key] = value;
+            if (carried.Count > 0) state["carried_values"] = carried;
+            if (viewGraphics && ViewGraphicsOf(derived) is { } graphics) state["view_graphics"] = graphics;
+            if (state.Count == 0 || (state.Count == 1 && state.ContainsKey("derived_from"))) return null;
+            state["check"] = ElementCheck;
+            return state;
+        }
+
+        /// <summary>Views that hide or override this element, within ScanBudget.</summary>
+        private static Dictionary<string, object?>? ViewGraphicsOf(Element element)
+        {
+            var clock = Stopwatch.StartNew();
+            var hiddenIn = new List<long>();
+            int overriddenIn = 0;
+            bool complete = true;
+            foreach (var view in new FilteredElementCollector(element.Document).OfClass(typeof(View)).Cast<View>())
+            {
+                if (clock.Elapsed > ScanBudget) { complete = false; break; }
+                if (view.IsTemplate) continue;
+                try
+                {
+                    if (element.CanBeHidden(view) && element.IsHidden(view)) hiddenIn.Add(view.Id.Value);
+                    if (view.AreGraphicsOverridesAllowed() && IsNonDefault(view.GetElementOverrides(element.Id))) overriddenIn++;
+                }
+                catch (Autodesk.Revit.Exceptions.ArgumentException) { }
+                catch (Autodesk.Revit.Exceptions.InvalidOperationException) { }
+            }
+            if (hiddenIn.Count == 0 && overriddenIn == 0 && complete) return null;
+            return new Dictionary<string, object?>
+            {
+                ["hidden_in_views"] = hiddenIn.Count, ["hidden_in_view_ids"] = hiddenIn.Take(SampleCap).ToList(),
+                ["overridden_in_views"] = overriddenIn, ["complete"] = complete,
+            };
+        }
+    }
+}