From fcf1ea22e9ea6ca23147e47c50934f9ed0b20c4c Mon Sep 17 00:00:00 2001 From: Pasukhin Dmitry Date: Wed, 29 Jul 2026 00:36:13 +0100 Subject: [PATCH] Documentation, Configuration - Correct guides and generation setup (#1404) Correct obsolete API references, code examples, terminology, links, and contribution workflow instructions across the documentation. Generate Doxygen example paths from OCCT package metadata and fix license markup. Remove obsolete documentation CMake, layout, and unused PDF generation files. --- .github/CLA_SIGNING.md | 2 +- .github/CONTRIBUTING.md | 4 +- .gitignore | 17 ++ README.md | 8 +- adm/cmake/occt_doc.cmake | 101 ++-------- dox/CMakeLists.txt | 125 ------------ dox/DoxygenLayout.xml | 188 ------------------ dox/FILES_PDF.txt | 32 --- .../contribution_workflow.md | 2 +- dox/contribution/git_guide/git_guide.md | 14 +- dox/contribution/tests/tests.md | 6 +- dox/license.md | 2 +- dox/resources/occt_pdf_template.tex | 151 -------------- dox/resources/occt_ug_pdf.doxyfile | 52 ----- dox/samples/ais_object.md | 4 +- dox/samples/ocaf.md | 14 +- .../boolean_operations/boolean_operations.md | 10 +- dox/specification/brep_format.md | 2 +- dox/specification/pbr_math.md | 10 +- dox/upgrade/upgrade.md | 4 +- .../foundation_classes/foundation_classes.md | 17 +- dox/user_guides/iges/iges.md | 3 +- .../modeling_algos/modeling_algos.md | 14 +- .../modeling_data/modeling_data.md | 4 +- .../shape_healing/shape_healing.md | 14 +- dox/user_guides/step/step.md | 15 +- .../visualization/visualization.md | 8 +- dox/user_guides/xde/xde.md | 2 +- 28 files changed, 117 insertions(+), 708 deletions(-) delete mode 100644 dox/CMakeLists.txt delete mode 100644 dox/DoxygenLayout.xml delete mode 100644 dox/FILES_PDF.txt delete mode 100644 dox/resources/occt_pdf_template.tex delete mode 100644 dox/resources/occt_ug_pdf.doxyfile diff --git a/.github/CLA_SIGNING.md b/.github/CLA_SIGNING.md index ce1ff7518d..8b6e7332e6 100644 --- a/.github/CLA_SIGNING.md +++ b/.github/CLA_SIGNING.md @@ -13,7 +13,7 @@ Accepting and signing the Contributor License Agreement is a prerequisite for co 2. Download the Contribution License Agreement pdf file and print it 3. Read the agreement and sign it 4. Scan the signed CLA to a pdf file -5. If not yet done, log on to this website +5. If not yet done, log on to [the OCCT development portal](https://dev.opencascade.org) 6. In the CLA sending form, press the "Browse" button 7. Select your signed CLA file 8. Press "Send" diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fe41af8a8d..b85060b97a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -11,10 +11,10 @@ In order to contribute code to OCCT you must sign the Contributor License Agreem ### Steps to Submit Your Contribution 1. **Fork the repository** on GitHub: https://github.com/Open-Cascade-SAS/OCCT -2. **Create a feature branch** from an up-to-date `master`. Any descriptive branch name is fine. +2. **Create a feature branch** from an up-to-date `IR`. Any descriptive branch name is fine. 3. **Develop your change** following the [OCCT Coding Rules](https://dev.opencascade.org/doc/overview/html/occt_contribution__coding_rules.html). Format the source with `clang-format` using the `.clang-format` configuration shipped in the repository. 4. **Test locally**. Run the existing DRAW test suite and `OpenCascadeGTest` tests; create a test case for the change when applicable. -5. **Open a Draft Pull Request** against `Open-Cascade-SAS/OCCT:master`. CI/CD pipelines run on every push and report build, style and test results. +5. **Open a Draft Pull Request** against `Open-Cascade-SAS/OCCT:IR`. CI/CD pipelines run on every push and report build, style and test results. 6. **Mark the PR Ready for Review** once CI is green. A maintainer will review the change and request updates as needed. 7. **Address review feedback** by pushing additional commits to the same branch; CI re-runs automatically. 8. After approval the PR is merged (typically squashed) by a maintainer. diff --git a/.gitignore b/.gitignore index ccceb47426..571f41a5b3 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ !/cmake/ !/data/ !/dox/ +!/resources/ !/src/ !/tests/ !/.github/ @@ -44,6 +45,22 @@ !/src/Visualization/ !/src/Deprecated/ +# resources/ level: Ignore everything except tracked items +/resources/* +!/resources/BOPAlgo/ +!/resources/DrawResources/ +!/resources/samples +!/resources/Shaders/ +!/resources/SHMessage/ +!/resources/StdResource/ +!/resources/Textures/ +!/resources/TObj/ +!/resources/UnitsAPI/ +!/resources/XmlOcafResource/ +!/resources/XRResources/ +!/resources/XSMessage/ +!/resources/XSTEPResource/ + # ============================================================================ # DEEPER LEVEL RULES (applied recursively within allowed directories above) # ============================================================================ diff --git a/README.md b/README.md index 13ee509951..24429adbc2 100644 --- a/README.md +++ b/README.md @@ -28,17 +28,17 @@ You can also find OCCT pre-installed on your system or install it from packages Documentation is available at the following links: - [Latest version](https://dev.opencascade.org/doc/overview) -- [Version 7.8](https://dev.opencascade.org/doc/occt-7.8.0/overview) +- [Version 8.0](https://dev.opencascade.org/doc/occt-8.0.0/overview) Documentation can be part of the package. To preview documentation as part of the package, open the file `doc/html/index.html` to browse HTML documentation. If HTML documentation is not available in your package, you can: - **Generate it from sources:** You need to have Tcl and Doxygen 1.8.4 (or above) installed on your system and accessible in your environment (check the environment variable PATH). Use the batch file `adm/gendoc.bat` on Windows or the Bash script `adm/gendoc` on Linux or OS X to (re)generate documentation. -- **Generate together with sources:** You need to have CMake and 1.8.4 (or above) installed on your system. Enable `BUILD_DOC_Overview` CMake parameter and set the path to Doxygen `3RDPARTY_DOXYGEN_EXECUTABLE`. Then build ALL or only `Overview`. +- **Generate together with sources:** You need to have CMake and Doxygen 1.8.4 (or above) installed on your system. Enable `BUILD_DOC_Overview` CMake parameter and set the path to Doxygen `3RDPARTY_DOXYGEN_EXECUTABLE`. Then build ALL or only `Overview`. - **Read documentation in source plain text (Markdown) format** found in the subfolder `dox` or [GitHub Wiki](https://github.com/Open-Cascade-SAS/OCCT/wiki). -See [dox/build/build_documentation/building_documentation.md](dox/build/build_documentation/building_documentation.md) or [Building Documentation](https://dev.opencascade.org/doc/occt-7.8.0/overview/html/build_upgrade__building_documentation.html) for details. +See [dox/build/build_documentation/building_documentation.md](dox/build/build_documentation/building_documentation.md) or [Building Documentation](https://dev.opencascade.org/doc/occt-8.0.0/overview/html/build_upgrade__building_documentation.html) for details. ## Building @@ -57,7 +57,7 @@ The current version of OCCT can be found in the file [`adm/cmake/version.cmake`] - [OCCT Tracker](https://tracker.dev.opencascade.org/) For information regarding OCCT code development, please consult the official OCCT Collaborative Development Portal: -- [OCCT Development Portal](http://dev.opencascade.org) +- [OCCT Development Portal](https://dev.opencascade.org) ### Forum and Discussions - [OCCT Forums](https://dev.opencascade.org/forums) diff --git a/adm/cmake/occt_doc.cmake b/adm/cmake/occt_doc.cmake index 5ec9c8ef21..3b6e09b395 100644 --- a/adm/cmake/occt_doc.cmake +++ b/adm/cmake/occt_doc.cmake @@ -265,15 +265,6 @@ function(OCCT_DOC_LOAD_FILE_LISTS) else() set(OCCT_DOC_HTML_FILES "" PARENT_SCOPE) endif() - - # Load list of PDF documentation files - set(FILES_PDF_PATH "${OCCT_ROOT_DIR}/dox/FILES_PDF.txt") - if(EXISTS ${FILES_PDF_PATH}) - file(STRINGS ${FILES_PDF_PATH} PDF_FILES REGEX "^[^#]+") - set(OCCT_DOC_PDF_FILES ${PDF_FILES} PARENT_SCOPE) - else() - set(OCCT_DOC_PDF_FILES "" PARENT_SCOPE) - endif() endfunction() # Function to collect image directories from input files @@ -363,6 +354,26 @@ function(OCCT_DOC_CONFIGURE_DOXYGEN OUTPUT_DIR CONFIG_FILE DOC_TYPE) file(APPEND ${DOXYGEN_CONFIG_FILE} "ENABLED_SECTIONS = OVERVIEW_SECTION\n") file(APPEND ${DOXYGEN_CONFIG_FILE} "GENERATE_TAGFILE = ${OUTPUT_DIR}/occt.tag\n") file(APPEND ${DOXYGEN_CONFIG_FILE} "GENERATE_TREEVIEW = YES\n") + + set(EXAMPLE_DIRS "") + foreach(MODULE ${OCCT_MODULES}) + foreach(TOOLKIT ${TOOLKITS_IN_MODULE_${MODULE}}) + foreach(PACKAGE ${PACKAGES_IN_TOOLKIT_${TOOLKIT}}) + EXTRACT_PACKAGE_FILES("src" ${PACKAGE} _ PACKAGE_DIR) + if(PACKAGE_DIR) + list(APPEND EXAMPLE_DIRS "${PACKAGE_DIR}") + endif() + endforeach() + endforeach() + endforeach() + list(REMOVE_DUPLICATES EXAMPLE_DIRS) + + set(EXAMPLE_PATHS "") + foreach(EXAMPLE_DIR ${EXAMPLE_DIRS}) + string(APPEND EXAMPLE_PATHS " \"${EXAMPLE_DIR}\"") + endforeach() + file(APPEND ${DOXYGEN_CONFIG_FILE} "EXAMPLE_PATH =${EXAMPLE_PATHS}\n") + file(APPEND ${DOXYGEN_CONFIG_FILE} "EXAMPLE_PATTERNS = *.cxx\n") # Setup tag file for cross-referencing with Reference Manual if(BUILD_DOC_RefMan) @@ -479,25 +490,6 @@ function(OCCT_DOC_CHECK_TOOLS) set(MATHJAX_PATH "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5") endif() - # Find tools for PDF generation if needed - if(BUILD_DOC_PDF) - # Find pdflatex - find_program(PDFLATEX_EXECUTABLE NAMES pdflatex) - if(NOT PDFLATEX_EXECUTABLE) - message(WARNING "pdflatex not found. PDF documentation will not be generated.") - set(BUILD_DOC_PDF FALSE PARENT_SCOPE) - endif() - - # Find Inkscape (for SVG to PNG conversion for PDFs) - find_program(INKSCAPE_EXECUTABLE NAMES inkscape) - if(NOT INKSCAPE_EXECUTABLE) - message(WARNING "Inkscape not found. SVG images will not be properly converted in PDF documentation.") - endif() - - set(PDFLATEX_EXECUTABLE ${PDFLATEX_EXECUTABLE} PARENT_SCOPE) - set(INKSCAPE_EXECUTABLE ${INKSCAPE_EXECUTABLE} PARENT_SCOPE) - endif() - # Find tools for CHM generation if needed if(BUILD_DOC_CHM AND WIN32) # Find HTML Help Compiler @@ -515,59 +507,6 @@ function(OCCT_DOC_CHECK_TOOLS) set(OCCT_DOC_TOOLS_AVAILABLE TRUE PARENT_SCOPE) endfunction() -# Function to process LaTeX files for PDF generation -function(OCCT_DOC_PROCESS_LATEX OUTPUT_DIR) - # Skip if PDF generation is not enabled or pdflatex not found - if(NOT BUILD_DOC_PDF OR NOT PDFLATEX_EXECUTABLE) - return() - endif() - - message(STATUS "Processing LaTeX files for PDF generation...") - - # Process SVG images if Inkscape is available - if(INKSCAPE_EXECUTABLE) - file(GLOB SVG_FILES "${OUTPUT_DIR}/latex/*.svg") - foreach(SVG_FILE ${SVG_FILES}) - get_filename_component(FILE_NAME ${SVG_FILE} NAME_WE) - set(PNG_FILE "${OUTPUT_DIR}/latex/${FILE_NAME}.png") - - execute_process( - COMMAND ${INKSCAPE_EXECUTABLE} -z -e ${PNG_FILE} ${SVG_FILE} - RESULT_VARIABLE INKSCAPE_RESULT - ) - - if(NOT INKSCAPE_RESULT EQUAL 0) - message(WARNING "Failed to convert ${SVG_FILE} to PNG") - endif() - endforeach() - endif() - - # Generate PDF from LaTeX - execute_process( - COMMAND ${PDFLATEX_EXECUTABLE} -interaction=nonstopmode refman.tex - WORKING_DIRECTORY "${OUTPUT_DIR}/latex" - RESULT_VARIABLE LATEX_RESULT - OUTPUT_VARIABLE LATEX_OUTPUT - ERROR_VARIABLE LATEX_ERROR - ) - - if(NOT LATEX_RESULT EQUAL 0) - message(WARNING "Error generating PDF: ${LATEX_ERROR}") - else() - # Run pdflatex again for references - execute_process( - COMMAND ${PDFLATEX_EXECUTABLE} -interaction=nonstopmode refman.tex - WORKING_DIRECTORY "${OUTPUT_DIR}/latex" - ) - - message(STATUS "PDF documentation generated at ${OUTPUT_DIR}/latex/refman.pdf") - - # Copy the PDF to a more accessible location - file(COPY "${OUTPUT_DIR}/latex/refman.pdf" DESTINATION "${OUTPUT_DIR}") - file(RENAME "${OUTPUT_DIR}/refman.pdf" "${OUTPUT_DIR}/${DOC_OUTPUT_NAME}.pdf") - endif() -endfunction() - # Main function to set up documentation targets function(OCCT_SETUP_DOC_TARGETS) # Check if required tools are available diff --git a/dox/CMakeLists.txt b/dox/CMakeLists.txt deleted file mode 100644 index 83b4d5f562..0000000000 --- a/dox/CMakeLists.txt +++ /dev/null @@ -1,125 +0,0 @@ -project (Overview) - -# directory that contains all raw OCCT overview articles (markdown format) -set (OCCT_OVERVIEW_DIR "${OCCT_ROOT_DIR}/dox") - -# directory that contains resources for the generation of OCCT documentation -set (OCCT_OVERVIEW_RESOURCE_DIR "${OCCT_OVERVIEW_DIR}/resources") - -# directory that contains all generated OCCT articles -set (OCCT_GENERATED_DOC_DIR "${CMAKE_BINARY_DIR}/doc") -if (NOT EXISTS "${OCCT_GENERATED_DOC_DIR}") - file (MAKE_DIRECTORY "${OCCT_GENERATED_DOC_DIR}") -endif() - -# directory that contains generated OCCT overview articles -set (OCCT_GENERATED_OVERVIEW_DIR "${OCCT_GENERATED_DOC_DIR}/overview") -if (NOT EXISTS "${OCCT_GENERATED_OVERVIEW_DIR}") - file (MAKE_DIRECTORY "${OCCT_GENERATED_OVERVIEW_DIR}") -endif() - -# directory that contains generated OCCT overview articles in html format -set (OCCT_GENERATED_HTML_OVERVIEW_DIR "${OCCT_GENERATED_OVERVIEW_DIR}/html") -if (NOT EXISTS "${OCCT_GENERATED_HTML_OVERVIEW_DIR}") - file (MAKE_DIRECTORY "${OCCT_GENERATED_HTML_OVERVIEW_DIR}") -endif() - -# read OCCT articles that should be generated -set (OCCT_ARTICLES "") -if (EXISTS "${OCCT_OVERVIEW_DIR}/FILES_HTML.txt" ) - file (STRINGS "${OCCT_OVERVIEW_DIR}/FILES_HTML.txt" OCCT_ARTICLES REGEX "^[^#]+") -else() - message (FATAL_ERROR "FILES_HTML.txt is not found in ${OCCT_OVERVIEW_DIR}") -endif() - -# configuration file for doxygen -set (OCCT_CONFIG_FOR_DOXYGEN "${OCCT_GENERATED_DOC_DIR}/occt.cfg") - -set (3RDPARTY_MATHJAX_RELATIVE_PATH "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1") - -configure_file ("${OCCT_OVERVIEW_RESOURCE_DIR}/occt_ug_html.doxyfile" "${OCCT_CONFIG_FOR_DOXYGEN}" COPYONLY) - -# Add common options for generation of Overview and User Guides -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nPROJECT_NUMBER = ${OCC_VERSION_STRING_EXT}") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nOUTPUT_DIRECTORY = ${OCCT_GENERATED_OVERVIEW_DIR}/.") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nPROJECT_LOGO = ${OCCT_OVERVIEW_DIR}/resources/occ_logo.png") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nEXAMPLE_PATH = ${OCCT_ROOT_DIR}/src ${OCCT_ROOT_DIR}/src/Draw/TKViewerTest/ViewerTest") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nEXAMPLE_PATTERNS = *.cxx") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nEXAMPLE_RECURSIVE = YES") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nWARN_AS_ERROR = NO") - -set (OCCT_ARTICLE_PARAM_INPUT "INPUT =") -set (OCCT_ARTICLE_PARAM_IMAGEPATH "IMAGE_PATH = ${OCCT_OVERVIEW_DIR}/resources/ ") - -set (OCCT_ARTICLES_ABSPATH "") -foreach (OCCT_ARTICLE ${OCCT_ARTICLES}) - get_filename_component (OCCT_ARTICLE_ABSOLUTE_PATH "${OCCT_OVERVIEW_DIR}/${OCCT_ARTICLE}" ABSOLUTE) - get_filename_component (OCCT_ARTICLE_PARENT_DIR "${OCCT_ARTICLE_ABSOLUTE_PATH}" PATH) - - if (EXISTS "${OCCT_ARTICLE_PARENT_DIR}/images") - set (OCCT_ARTICLE_PARAM_IMAGEPATH "${OCCT_ARTICLE_PARAM_IMAGEPATH} ${OCCT_ARTICLE_PARENT_DIR}/images") - endif() - - set (OCCT_ARTICLE_PARAM_INPUT "${OCCT_ARTICLE_PARAM_INPUT} ${OCCT_ARTICLE_ABSOLUTE_PATH}") - - set (SOURCE_GROUP_NAME "") - - # add the file to appropriate source group - get_filename_component (CURRENT_TAIL_PATH "${OCCT_ARTICLE}" PATH) - while (CURRENT_TAIL_PATH AND NOT "${CURRENT_TAIL_PATH}" STREQUAL "..") - get_filename_component (CURRENT_DIR_NAME "${CURRENT_TAIL_PATH}" NAME) - set (SOURCE_GROUP_NAME "${CURRENT_DIR_NAME}\\${SOURCE_GROUP_NAME}") - - # one step out (get parent directory) - get_filename_component (CURRENT_TAIL_PATH "${CURRENT_TAIL_PATH}" PATH) - endwhile() - SOURCE_GROUP ("${SOURCE_GROUP_NAME}" FILES ${OCCT_ARTICLE_ABSOLUTE_PATH}) - - list (APPEND OCCT_ARTICLES_ABSPATH ${OCCT_ARTICLE_ABSOLUTE_PATH}) -endforeach() - -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\n${OCCT_ARTICLE_PARAM_INPUT}") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\n${OCCT_ARTICLE_PARAM_IMAGEPATH}") - -# Add document type-specific options -# generate tree view -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nGENERATE_TREEVIEW = YES") - -# HTML Search engine options -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nSEARCHENGINE = YES") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nSERVER_BASED_SEARCH = YES") -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nEXTERNAL_SEARCH = NO") - -# Formula options -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nMATHJAX_RELPATH = ${3RDPARTY_MATHJAX_RELATIVE_PATH}") - -# If MSVC is used as build system, change warning format to the one recognized by MSVC -if (MSVC) - file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nWARN_FORMAT = \"$file($line): $text\"") -endif() - -# Avoid Doxygen parsing messages in the build log -file (APPEND ${OCCT_CONFIG_FOR_DOXYGEN} "\nQUIET = YES") - -# Copy index file to provide fast access to HTML documentation -file(COPY "${OCCT_OVERVIEW_RESOURCE_DIR}/index.html" DESTINATION "${OCCT_GENERATED_OVERVIEW_DIR}") - -# get relative paths to documentation source files -file (GLOB_RECURSE OCCT_OVERVIEW_FILES "${OCCT_OVERVIEW_DIR}/*") - -add_custom_command(OUTPUT "${OCCT_GENERATED_DOC_DIR}/overview/html/occt_logo.png" - COMMAND ${3RDPARTY_DOXYGEN_EXECUTABLE} ${OCCT_CONFIG_FOR_DOXYGEN} - DEPENDS ${OCCT_OVERVIEW_FILES} - WORKING_DIRECTORY ${OCCT_GENERATED_DOC_DIR} - COMMENT "Generating OCCT overview documentation with Doxygen" - VERBATIM -) - -add_custom_target(${PROJECT_NAME} ALL - DEPENDS "${OCCT_GENERATED_DOC_DIR}/overview/html/occt_logo.png" ${OCCT_OVERVIEW_FILES} - SOURCES ${OCCT_ARTICLES_ABSPATH} - VERBATIM -) - -# Create Documentation folder in solution view -set_property (TARGET ${PROJECT_NAME} PROPERTY FOLDER "Documentation") diff --git a/dox/DoxygenLayout.xml b/dox/DoxygenLayout.xml deleted file mode 100644 index 21d15aaef8..0000000000 --- a/dox/DoxygenLayout.xml +++ /dev/null @@ -1,188 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/dox/FILES_PDF.txt b/dox/FILES_PDF.txt deleted file mode 100644 index 549e080868..0000000000 --- a/dox/FILES_PDF.txt +++ /dev/null @@ -1,32 +0,0 @@ -# This file contains list of documentation files of OCCT which are processed -# by Doxygen to generate PDF documentation. -# Files are listed one file per line, with paths relative to dox folder. -# Empty spaces are allowed. -# Strings starting with '#' are treated as comments and ignored. - -tutorial/tutorial.md - -upgrade/upgrade.md - -user_guides/foundation_classes/foundation_classes.md -user_guides/modeling_data/modeling_data.md -user_guides/modeling_algos/modeling_algos.md -user_guides/mesh/mesh.md -user_guides/ocaf/ocaf.md -user_guides/visualization/visualization.md -user_guides/vis/vis.md -user_guides/iges/iges.md -user_guides/step/step.md -user_guides/xde/xde.md -user_guides/de_wrapper/de_wrapper.md -user_guides/draw_test_harness/draw_test_harness.md - -contribution/contribution_workflow/contribution_workflow.md -contribution/documentation/documentation.md -contribution/coding_rules.md -contribution/git_guide/git_guide.md -contribution/tests/tests.md - -specification/boolean_operations/boolean_operations.md -specification/brep_format.md -specification/pbr_math.md diff --git a/dox/contribution/contribution_workflow/contribution_workflow.md b/dox/contribution/contribution_workflow/contribution_workflow.md index e5910b6ea1..c1f5d556da 100644 --- a/dox/contribution/contribution_workflow/contribution_workflow.md +++ b/dox/contribution/contribution_workflow/contribution_workflow.md @@ -91,7 +91,7 @@ Re-formatting of unrelated code should be avoided unless done in a dedicated PR. @subsection occt_contribution_workflow_test Providing a Test Case For functional changes, a test case should be created (unless an existing test already covers it). -See @ref testmanual_intro_quick_create "Creating a New Test" for instructions. +See @ref testmanual_3 "Creating a New Test" for instructions. Test data files (CAD models, etc.) should be attached to the GitHub Issue or PR. diff --git a/dox/contribution/git_guide/git_guide.md b/dox/contribution/git_guide/git_guide.md index 677d4f506d..ec5938ca6d 100644 --- a/dox/contribution/git_guide/git_guide.md +++ b/dox/contribution/git_guide/git_guide.md @@ -30,7 +30,7 @@ Or via SSH: @subsection occt_gitguide_1_3 Repository Content - **master** branch: the current development version. Official releases are marked by tags. -- **IR** branch: the weekly integration branch where contributions are merged after review and CI/CD checks. +- **IR** branch: the integration branch where contributions are merged after review and CI/CD checks. - Topic branches for feature development, bug fixes, and improvements. @subsection occt_gitguide_1_4 Quick Rules @@ -103,11 +103,11 @@ ssh -T git@github.com @subsection occt_gitguide_3_1 Create a Branch -Always create branches from an up-to-date master: +Always create branches from an up-to-date `IR` branch: ~~~~ -git checkout master -git pull upstream master +git checkout IR +git pull upstream IR git checkout -b my-feature-branch ~~~~ @@ -169,9 +169,9 @@ PRs are typically squashed into a single commit on IR. Regularly sync your fork with upstream: ~~~~ -git checkout master -git pull upstream master -git push origin master +git checkout IR +git pull upstream IR +git push origin IR ~~~~ @section occt_gitguide_4 Rebasing diff --git a/dox/contribution/tests/tests.md b/dox/contribution/tests/tests.md index 311cca1529..f9cf433991 100644 --- a/dox/contribution/tests/tests.md +++ b/dox/contribution/tests/tests.md @@ -114,7 +114,7 @@ Example: ~~~~ Draw[]> testgrid -outdir d:/occt/last_results -overwrite ~~~~ -In the output directory, a cumulative HTML report summary.html provides links to reports on each test case. An additional report in JUnit-style XML format can be output for use in Jenkins or other continuous integration system. +In the output directory, a cumulative HTML report summary.html provides links to reports on each test case. An additional report in JUnit-style XML format can be output for use in GitHub Actions or other continuous integration systems. To re-run the test cases, which were detected as regressions on the previous run, option -regress dirname should be used. dirname is a path to the directory containing the results of the previous run. Only the test cases with *FAILED* and *IMPROVEMENT* statuses will be tested. @@ -567,7 +567,7 @@ During execution of a test, the following Tcl variables are defined on global le |-----------|-------| | dirname | Path to the root directory of the current set of test scripts | | groupname | Name of the test group (subfolder of $dirname) | -| gridname | Name of the test grid (subfolder of $dirname/$gridname) | +| gridname | Name of the test grid (subfolder of $dirname/$groupname/$gridname) | | casename | Name of the test | | imagedir | Path to folder where test log and other artifacts are saved | @@ -1088,7 +1088,7 @@ This group allows testing extended data exchange packages. | Data Exchange | TKDESTL, TKDEVRML | stlvrml | | Data Exchange | TKXSBase, TKXCAF, TKXmlXCAF, TKBinXCAF | xde | | Foundation Classes | TKernel, TKMath | fclasses | -| Modeling_algorithms | TKGeomAlgo, TKTopAlgo, TKPrim, TKBO, TKBool, TKHLR, TKFillet, TKOffset, TKFeat, TKXMesh | modalg | +| ModelingAlgorithms | TKGeomAlgo, TKTopAlgo, TKPrim, TKBO, TKBool, TKHLR, TKFillet, TKOffset, TKFeat, TKXMesh | modalg | | Modeling Data | TKG2d, TKG3d, TKGeomBase, TKBRep | moddata | | Visualization | TKService, TKV3d, TKOpenGl, TKMeshVS | vis | diff --git a/dox/license.md b/dox/license.md index bc82745bf3..c120e7f319 100644 --- a/dox/license.md +++ b/dox/license.md @@ -500,7 +500,7 @@ school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the - library `Frob' (a library for tweaking knobs) written by James Random Hacker. + library 'Frob' (a library for tweaking knobs) written by James Random Hacker. , 1 April 1990 Ty Coon, President of Vice diff --git a/dox/resources/occt_pdf_template.tex b/dox/resources/occt_pdf_template.tex deleted file mode 100644 index ff6ec5488b..0000000000 --- a/dox/resources/occt_pdf_template.tex +++ /dev/null @@ -1,151 +0,0 @@ -\batchmode -\nonstopmode -\documentclass[oneside]{article} -\n -% Packages required by doxygen -\usepackage{calc} -\usepackage{doxygen} -\usepackage{graphicx} -\usepackage[utf8]{inputenc} -\usepackage{makeidx} -\usepackage{multicol} -\usepackage{multirow} -\usepackage{textcomp} -\usepackage{amsmath} -\usepackage[table]{xcolor} -\usepackage{indentfirst} - -% Font selection -\usepackage[T1]{fontenc} -\usepackage{mathptmx} -\usepackage[scaled=.90]{helvet} -\usepackage{courier} -\usepackage{amssymb} -\usepackage{sectsty} -\renewcommand{\familydefault}{\sfdefault} -\allsectionsfont{% - \fontseries{bc}\selectfont% - \color{darkgray}% -} -\renewcommand{\DoxyLabelFont}{% - \fontseries{bc}\selectfont% - \color{darkgray}% -} -\newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} - -% Page & text layout -\usepackage{geometry} -\geometry{% - a4paper,% - top=2.5cm,% - bottom=2.5cm,% - left=2.5cm,% - right=2.5cm% -} -\tolerance=750 -\hfuzz=15pt -\hbadness=750 -\setlength{\emergencystretch}{15pt} -\setlength{\parindent}{0cm} -\setlength{\parskip}{0.2cm} -\makeatletter -\renewcommand{\paragraph}{% - \@startsection{paragraph}{4}{0ex}{-1.0ex}{1.0ex}{% - \normalfont\normalsize\bfseries\SS@parafont% - }% -} -\renewcommand{\subparagraph}{% - \@startsection{subparagraph}{5}{0ex}{-1.0ex}{1.0ex}{% - \normalfont\normalsize\bfseries\SS@subparafont% - }% -} -\makeatother - -% Headers & footers -\usepackage{fancyhdr} -\pagestyle{fancyplain} -\fancyhead[LE]{\fancyplain{}{\bfseries\thepage}} -\fancyhead[CE]{\fancyplain{}{}} -\fancyhead[RE]{\fancyplain{}{\bfseries\leftmark}} -\fancyhead[LO]{\fancyplain{}{\bfseries\rightmark}} -\fancyhead[CO]{\fancyplain{}{}} -\fancyhead[RO]{\fancyplain{}{\bfseries\thepage}} -\fancyfoot[LE]{\fancyplain{}{}} -\fancyfoot[CE]{\fancyplain{}{}} -\fancyfoot[RE]{\fancyplain{}{\bfseries\scriptsize (c) Open CASCADE DEFYEAR}} -\fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize (c) Open CASCADE DEFYEAR}} -\fancyfoot[CO]{\fancyplain{}{}} -\fancyfoot[RO]{\fancyplain{}{}} -\renewcommand{\footrulewidth}{0.4pt} -\renewcommand{\sectionmark}[1]{% - \markright{\thesection\ #1}% -} - -% Indices & bibliography -\usepackage{natbib} -\usepackage[titles]{tocloft} -\renewcommand{\cftsecleader}{\cftdotfill{\cftdotsep}} -\setcounter{tocdepth}{3} -\setcounter{secnumdepth}{5} -\makeindex - -% Hyperlinks (required, but should be loaded last) -\usepackage{ifpdf} -\ifpdf - \usepackage[pdftex,pagebackref=true]{hyperref} -\else - \usepackage[ps2pdf,pagebackref=true]{hyperref} -\fi -\hypersetup{% - colorlinks=true,% - linkcolor=blue,% - citecolor=black,% - urlcolor=blue,% - unicode% -} - -% Custom commands -\newcommand{\clearemptydoublepage}{% - \newpage{\pagestyle{empty}\cleardoublepage}% -} - - -%===== C O N T E N T S ===== - -\begin{document} - -% Titlepage & ToC -\hypersetup{pageanchor=false} -\pagenumbering{roman} -\begin{titlepage} -\vspace*{7cm} -\begin{center}% -\includegraphics[width=0.75\textwidth, height=0.2\textheight]{../../../dox/resources/occt_logo.png}\\ -{\Large Open C\-A\-S\-C\-A\-D\-E Technology \\\\\Large DEFCASVERSION }\\ -\vspace*{1cm} -{\Large DEFDOCLABEL}\\ -\vspace*{1cm} -\vspace*{0.5cm} -{\small \today}\ -\end{center} -\end{titlepage} -\clearpage -\pagenumbering{roman} -\newpage -\pagenumbering{arabic} - \begingroup - \hypersetup{pageanchor=true, linkcolor=black, colorlinks=true} - \tableofcontents - \endgroup - -\let\stdsection\section - \renewcommand\section{\pagebreak\stdsection} -\hypertarget{DEFFILENAME}{} -\input{DEFFILENAME} - -% Index -\newpage -\phantomsection -\addcontentsline{toc}{part}{Index} -\printindex\n -\end{document} diff --git a/dox/resources/occt_ug_pdf.doxyfile b/dox/resources/occt_ug_pdf.doxyfile deleted file mode 100644 index 8457345812..0000000000 --- a/dox/resources/occt_ug_pdf.doxyfile +++ /dev/null @@ -1,52 +0,0 @@ -DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = "Open CASCADE Technology" -PROJECT_BRIEF = -CREATE_SUBDIRS = NO -OUTPUT_LANGUAGE = English -ABBREVIATE_BRIEF = -FULL_PATH_NAMES = YES -INHERIT_DOCS = YES -TAB_SIZE = 4 -MARKDOWN_SUPPORT = YES -EXTRACT_ALL = YES -CASE_SENSE_NAMES = NO -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO -INPUT_ENCODING = UTF-8 -FILE_PATTERNS = *.md *.dox -RECURSIVE = YES -SOURCE_BROWSER = NO -INLINE_SOURCES = YES -GENERATE_DOCSET = NO -GENERATE_CHI = NO -GENERATE_QHP = NO -GENERATE_ECLIPSEHELP = NO -GENERATE_RTF = NO -GENERATE_MAN = NO -GENERATE_XML = NO -GENERATE_DOCBOOK = NO -GENERATE_AUTOGEN_DEF = NO -GENERATE_PERLMOD = NO -STRIP_CODE_COMMENTS = NO -GENERATE_HTMLHELP = NO -GENERATE_HTML = NO -DISABLE_INDEX = YES -GENERATE_TREEVIEW = NO -PREDEFINED = PDF_ONLY -GENERATE_LATEX = YES -COMPACT_LATEX = YES -PDF_HYPERLINKS = YES -USE_PDFLATEX = YES -LATEX_BATCHMODE = YES -LATEX_OUTPUT = latex -LATEX_CMD_NAME = latex -MAKEINDEX_CMD_NAME = makeindex - -# Define alias for inserting images in uniform way (both HTML and PDF) -ALIASES += figure{1}="\image latex \1 \n" -ALIASES += figure{2}="\image latex \1 \2 \n" -ALIASES += figure{3}="\image latex \1 \2 width=\3 \n" diff --git a/dox/samples/ais_object.md b/dox/samples/ais_object.md index 9c270465e0..1bb11fcf75 100644 --- a/dox/samples/ais_object.md +++ b/dox/samples/ais_object.md @@ -172,7 +172,7 @@ aCtx->Display (aPrs, 1, 0, true); @figure{images/ais_object_step1_bndbox.png,"@c Prs3d_BndBox presentation builder.",409} height=409px @c AIS disallows activating multiple display modes at the same time, so that these presentation modes should be alternatives to each other. -But @c AIS may use non-active display mode for highlighting purposes - like wireframe (@c AIS_Wireframe) presentation displayed on top of shaded (@c AIS_Shaded) presentation for selected @c AIS_Shape objects. +But @c AIS may use non-active display mode for highlighting purposes - like wireframe (@c AIS_WireFrame) presentation displayed on top of shaded (@c AIS_Shaded) presentation for selected @c AIS_Shape objects. Let's define a dedicated enumeration for display modes supported by our interactive object and setup the 1st (@c MyDispMode_Highlight) display mode for highlighting with help of @c PrsMgr_PresentableObject::SetHilightMode(): @@ -736,7 +736,7 @@ void MyAisOwner::HilightWithColor (const occ::handle occ::handle aGroup = aPrs->NewGroup(); aGroup->SetGroupPrimitivesAspect (theStyle->ArrowAspect()->Aspect()); gp_Trsf aTrsfInv = mySelectable->LocalTransformation().Inverted(); - gp_Dir aNorm (aPickPnt.Normal.X(), aPickPnt.Normal.Y(), aPickPnt.Normal.Z()); + gp_Dir aNorm (aPickPnt.Normal.x(), aPickPnt.Normal.y(), aPickPnt.Normal.z()); occ::handle aTris = Prs3d_Arrow::DrawShaded (gp_Ax1(aPickPnt.Point, aNorm).Transformed (aTrsfInv), 1.0, 15.0, diff --git a/dox/samples/ocaf.md b/dox/samples/ocaf.md index 8efd35c2ea..8cb3bb8d2d 100644 --- a/dox/samples/ocaf.md +++ b/dox/samples/ocaf.md @@ -130,7 +130,7 @@ ad696001-5b34-11d1-b5ba-00a0c9064368.Location: TKStd //! This attribute implements a transformation data container class MyPackage_Transformation : public TDF_Attribute { -public: //!@ name Static methods +public: //! @name Static methods //! The method returns a unique GUID of this attribute. //! By means of this GUID this attribute may be identified @@ -141,12 +141,12 @@ public: //!@ name Static methods //! The found or created attribute is returned. Standard_EXPORT static occ::handle Set (const TDF_Label theLabel); -public: //!@ name Methods for access to the attribute data +public: //! @name Methods for access to the attribute data //! The method returns the transformation. Standard_EXPORT gp_Trsf Get () const; -public: //!@ name Methods for setting the data of transformation +public: //! @name Methods for setting the data of transformation //! The method defines a rotation type of transformation. Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, double theAngle); @@ -169,7 +169,7 @@ public: //!@ name Methods for setting the data of transformation //! The method defines a complex type of transformation from one coordinate system to another. Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2); -public: //!@ name Overridden methods from TDF_Attribute +public: //! @name Overridden methods from TDF_Attribute //! The method returns a unique GUID of the attribute. //! By means of this GUID this attribute may be identified among other attributes attached to the same label. @@ -185,12 +185,12 @@ public: //!@ name Overridden methods from TDF_Attribute //! The method is called on Copy / Paste. //! It copies the content of this attribute into theAttribute (copies the fields). - Standard_EXPORT void Paste (const occ::handle& theAttribute, const occ::handle& theRelocationTable); + Standard_EXPORT void Paste (const occ::handle& theAttribute, const occ::handle& theRelocationTable) const override; //! Prints the content of this attribute into the stream. - Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS); + Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS) const override; -public: //!@ name Constructor +public: //! @name Constructor //! The C++ constructor of this attribute class. //! Usually it is never called outside this class. diff --git a/dox/specification/boolean_operations/boolean_operations.md b/dox/specification/boolean_operations/boolean_operations.md index 789d1572b7..9bc78a0fd0 100644 --- a/dox/specification/boolean_operations/boolean_operations.md +++ b/dox/specification/boolean_operations/boolean_operations.md @@ -255,19 +255,19 @@ For a vertex *Vi* and a solid *Zj* there is Vertex/Solid interference if the ver @figure{/specification/boolean_operations/images/operations_image060.png,"Vertex/Solid Interference",220} -@subsubsection specification__boolean_3_1_8 Edge/Soild Interference +@subsubsection specification__boolean_3_1_8 Edge/Solid Interference For an edge *Ei* and a solid *Zj* there is Edge/Solid interference if the edge *Ei* and its sub-shapes have no BRep interferences with any sub-shape of *Zj* and *Ei* is completely inside the solid *Zj*. @figure{/specification/boolean_operations/images/operations_image061.png,"Edge/Solid Interference",220} -@subsubsection specification__boolean_3_1_9 Face/Soild Interference +@subsubsection specification__boolean_3_1_9 Face/Solid Interference For a face *Fi* and a solid *Zj* there is Face/Solid interference if the face *Fi* and its sub-shapes have no BRep interferences with any sub-shape of *Zj* and *Fi* is completely inside the solid *Zj*. @figure{/specification/boolean_operations/images/operations_image062.png,"Face/Solid Interference",220} -@subsubsection specification__boolean_3_1_10 Solid/Soild Interference +@subsubsection specification__boolean_3_1_10 Solid/Solid Interference For a solid *Zi* and a solid *Zj* there is Solid/Solid interference if the solid *Zi* and its sub-shapes have no BRep interferences with any sub-shape of *Zj* and *Zi* is completely inside the solid *Zj*. @@ -1632,11 +1632,11 @@ Let us consider two faces *F1* and *F2* that have a common edge: * The result of *Common* operation is an empty compound because the dimension (1) of the common part between *F1* and *F2* (edge)is less than the dimension of the arguments (2) -* The result of *Cut12* operation is a compound containing split part of the argument *F1*, i.e. new face *F11*. The vertices are shown just to clarify the fact that the edges are spitted. +* The result of *Cut12* operation is a compound containing split part of the argument *F1*, i.e. new face *F11*. The vertices are shown just to clarify the fact that the edges are split. @figure{/specification/boolean_operations/images/boolean_image038.png,"",230} -* The result of *Cut21* operation is a compound containing split parts of the argument *F2*, i.e. 1 new face *F21*. The vertices are shown just to clarify the fact that the edges are spitted. +* The result of *Cut21* operation is a compound containing split parts of the argument *F2*, i.e. 1 new face *F21*. The vertices are shown just to clarify the fact that the edges are split. @figure{/specification/boolean_operations/images/boolean_image039.png,"",230} diff --git a/dox/specification/brep_format.md b/dox/specification/brep_format.md index 78afb95ef2..7b3e0d032d 100644 --- a/dox/specification/brep_format.md +++ b/dox/specification/brep_format.md @@ -54,7 +54,7 @@ The following sample code reads a shape from ASCII file and writes it to a binar * \<_\\n\>: = " "*\<\\n\>; * \<_\>: = " "+; It is a not empty sequence of space characters with ASCII code 21h; * \: = "0" | "1"; - * \: It is an integer number from -231 to 231-1 which is written in denary system; + * \: It is an integer number from -231 to 231-1 which is written in decimal system; * \: It is a real from -1.7976931348623158 @f$\cdot@f$ 10308 to 1.7976931348623158 @f$\cdot@f$ 10308 which is written in decimal or E form with base 10.The point is used as a delimiter of the integer and fractional parts; * \: It is a real from -3.402823 @f$\cdot@f$ 1038 to 3.402823 @f$\cdot@f$ 1038 which is written in decimal or E form with base 10.The point is used as a delimiter of the integer and fractional parts; * \<2D point\>: = \\<_\>\; diff --git a/dox/specification/pbr_math.md b/dox/specification/pbr_math.md index 5007e938e5..137ab6338f 100644 --- a/dox/specification/pbr_math.md +++ b/dox/specification/pbr_math.md @@ -82,14 +82,14 @@ Going back to the BRDF the Cook-Torrance approach has the following expression: \f[f_s(v,l)=\frac{DGF}{4\cos\theta_l\cos\theta_v}\f] -Three parts presented in nominator have its own meaning but can have different implementation with various levels of complexity and physical accuracy. +Three parts presented in numerator have its own meaning but can have different implementation with various levels of complexity and physical accuracy. In that paper only one certain implementation is used. The \f$D\f$ component is responsible for **micro faces normals distribution**. It is the main instrument that controls reflection's shape and strength according to **roughness** \f$r\f$ parameter. The implementation with good visual results is **Trowbridge-Reitz GGX** approach used in Disney's RenderMan and Unreal Engine [@ref Karis13]: \f[D=\frac{\alpha^2}{\pi(\cos^2\theta_h(\alpha^2-1) + 1)^2}\f] -Where \f$\alpha = r^2\f$. This square in needed only for smoother roughness parameter control. +Where \f$\alpha = r^2\f$. This square is needed only for smoother roughness parameter control. Without it the visual appearance of surface becomes rough too quickly during the parameter's increasing. The second \f$G\f$ component is called **geometric shadowing** or attenuation factor. @@ -208,7 +208,7 @@ But it can be relatively easy implemented in case of environment illumination vi The next goal after \f$L_{direct}\f$ calculation is to find \f$L_{indirect}\f$. And it would be easier if \f$L_i^{indirect}(l)\f$ was known for every \f$l\f$. -That is the main assumption of **image based lightning** (**IBL**). +That is the main assumption of **image based lighting** (**IBL**). In practice, it can be achieved using environment image map, which is a special image representing illumination from all possible directions. This image might be a photo capturing a real world environment (spherical 360 degrees panoramas) or generated image baking the 3D scene itself, including in that case reflections of other objects. Environment image might be packed in different ways - **cube maps** and equirectangular maps are the most commonly used. @@ -336,7 +336,7 @@ All steps described above can be also done for hemisphere: \f[\theta = \arccos(1-u)\f] -Mote-Carlo integration cannot guarantee exact estimation of convergence speed with using random generated samples. +Monte-Carlo integration cannot guarantee exact estimation of convergence speed with using random generated samples. There is only probability estimation of it. But this algorithm is pretty universal and relatively simple to be applied to almost any function using at least uniform distributed points. Moreover special \f$p(l)\f$ can be chosen and special pseudo-random sequences can be designed in order to speed up convergence for some functions (following chapter talk about that in details). @@ -585,7 +585,7 @@ Using less samples produces image noise due to discrete nature of Monte-Carlo ap But it can be slightly smoothed using some prefiltration. The idea is that for the directions with small PDF or in other words for rare directions the samples near of it is unlikely to be generated. So that this direction represents the averaged illumination from relatively big area on hemisphere but approximate it by just a constant. -It wold be better to get from such direction already averaged over bigger area environment. +It would be better to get from such direction already averaged over bigger area environment. It can be achieved using mip levels of origin \f$L_i^{indirect}\f$ whose pixels of one level is exact 4 averaged pixels from previous one. Also mip levels generation is build in most common graphic API so there are no problems with it. But first of all the area covered by one sample is needed to be found. diff --git a/dox/upgrade/upgrade.md b/dox/upgrade/upgrade.md index 5c4e82b719..f0a2fe55a3 100644 --- a/dox/upgrade/upgrade.md +++ b/dox/upgrade/upgrade.md @@ -1672,10 +1672,10 @@ TColStd_Array1OfReal anArr; NCollection_Array TColgp_SequenceOfPnt aSeq; NCollection_Sequence aSeq; ~~~~ -Two package typedef wrappers have been removed entirely (no backward-compatible aliases): `TColGeom` and `TColGeom2d`. Replace with `NCollection_Array1>` and the equivalent `Geom2d_*` form: +The `TColGeom_*` and `TColGeom2d_*` collection typedefs have been deprecated (backward-compatible aliases are preserved with deprecation warnings). They will be removed in a future release. Replace them with the corresponding `NCollection_*` template instantiations, such as `NCollection_Array1>`: ~~~~{.cpp} -// Before (removed) // After +// Before (deprecated) // After #include #include TColGeom_Array1OfCurve aCurves; #include NCollection_Array1> aCurves; diff --git a/dox/user_guides/foundation_classes/foundation_classes.md b/dox/user_guides/foundation_classes/foundation_classes.md index 3282e4c23d..315e407145 100644 --- a/dox/user_guides/foundation_classes/foundation_classes.md +++ b/dox/user_guides/foundation_classes/foundation_classes.md @@ -344,7 +344,7 @@ To get the type descriptor for a given class type, use macro *STANDARD_TYPE()* w Example of usage: ~~~~{.cpp} -if (aCurve->IsKind(STANDARD_TYPE(Geom_Line))) // equivalent to "if (dynamic_cast(aCurve.get()) != 0)" +if (aCurve->IsKind(STANDARD_TYPE(Geom_Line))) // equivalent to "if (!occ::down_cast(aCurve).IsNull())" { ... } @@ -418,7 +418,7 @@ t = aSeq.Value (1); // here, you cannot write: // a = t; // ERROR ! // so you downcast: -a = occ::down_cast(t) +a = occ::down_cast(t); if (!a.IsNull()) { // types are compatible, you can use a @@ -695,7 +695,7 @@ The recommended location for it is first statement after opening brace of try As an example, consider the exceptions of type *Standard_NumericError, Standard_Overflow, Standard_Underflow* and *Standard_DivideByZero*, where *Standard_NumericError* is the parent type of the three others. ~~~~{.cpp} -void f(1) +void f() { try { @@ -720,7 +720,7 @@ The handlers are checked in order of appearance, from the nearest to the try blo For a try block, it would be a mistake to place a handler for a base exception type ahead of a handler for its derived type since that would ensure that the handler for the derived exception would never be invoked. ~~~~{.cpp} -void f(1) +void f() { int i = 0; { @@ -1221,7 +1221,7 @@ void Perform (const MyPackage_SequenceOfPnt& theSequence) { for (MyPackage_SequenceOfPnt::Iterator anIter (theSequence); anIter.More(); anIter.Next()) { - const gp_Pnt aPnt& = anIter.Value(); + const gp_Pnt& aPnt = anIter.Value(); ... } } @@ -1579,7 +1579,7 @@ Now the main program uses the math_Gauss class to solve the equations _a*x1=b1_ ~~~~{.cpp} #include #include -main() +int main() { math_Matrix a(1, 3, 1, 3); math_Vector b1(1, 3), b2(1, 3); @@ -1650,21 +1650,24 @@ public: virtual bool Value (const double x, double& f) override { f = myCoefA * x * x + myCoefB * x + myCoefC; + return true; } virtual bool Derivative (const double x, double& d) override { d = myCoefA * x * 2.0 + myCoefB; + return true; } virtual bool Values (const double x, double& f, double& d) override { f = myCoefA * x * x + myCoefB * x + myCoefC; d = myCoefA * x * 2.0 + myCoefB; + return true; } }; -main() +int main() { myFunction aFunc (1.0, 0.0, -4.0); // f(x) = x^2 - 4, root at x=2 math_BissecNewton aSol (0.000001); diff --git a/dox/user_guides/iges/iges.md b/dox/user_guides/iges/iges.md index 67257848b9..277b54a52a 100644 --- a/dox/user_guides/iges/iges.md +++ b/dox/user_guides/iges/iges.md @@ -432,7 +432,7 @@ Curves, which form the 2D of face boundaries, are translated as *Geom2D_Curves* | 141: Boundary | TopoDS_Wire | Same behavior as for the Curve On Surface (see below). The translation of a non-referenced Boundary IGES entity in a *BoundedSurface* IGES entity outputs a *TopoDS_Edge* or a *TopoDS_Wire* with a *Geom_Curve*. | | 142: Curve On Surface | TopoDS_Wire | Each *TopoDS_Edge* is defined by a 3D curve and by a 2D curve that references the surface. | -The type of OCCT shapes (either *TopDS_Edges* or *TopoDS_Wires*) that result from the translation of IGES entities 106, 112 and 126 depends on the continuity of the curve in the IGES file and the value of the *read.iges.bspline.continuity* translation parameter. +The type of OCCT shapes (either *TopoDS_Edges* or *TopoDS_Wires*) that result from the translation of IGES entities 106, 112 and 126 depends on the continuity of the curve in the IGES file and the value of the *read.iges.bspline.continuity* translation parameter. @subsubsection occt_iges_2_4_3 Surfaces Translation of a surface outputs either a *TopoDS_Face* or a *TopoDS_Shell*. @@ -1184,4 +1184,3 @@ bool statw = aWriter.Write (S); ~~~~ where S is OStream. - diff --git a/dox/user_guides/modeling_algos/modeling_algos.md b/dox/user_guides/modeling_algos/modeling_algos.md index 6fe086a8b0..9a4b51fd9f 100644 --- a/dox/user_guides/modeling_algos/modeling_algos.md +++ b/dox/user_guides/modeling_algos/modeling_algos.md @@ -888,7 +888,7 @@ double D = GeomAPI_ProjectPointOnCurve (P,C); int N = GeomAPI_ProjectPointOnCurve (P,C); ~~~~ -*gp_Pnt2d()* returns the nearest solution point. +*gp_Pnt()* returns the nearest solution point. ~~~~{.cpp} gp_Pnt P1 = GeomAPI_ProjectPointOnCurve (P,C); @@ -1006,7 +1006,7 @@ double D = GeomAPI_ProjectPointOnSurf (P,S); int N = GeomAPI_ProjectPointOnSurf (P,S); ~~~~ -*gp_Pnt2d()* returns the nearest solution point. +*gp_Pnt()* returns the nearest solution point. ~~~~{.cpp} gp_Pnt P1 = GeomAPI_ProjectPointOnSurf (P,S); @@ -1495,7 +1495,7 @@ The class *BRepPrimAPI_MakeBox* allows building a parallelepiped box. The result An error is raised if the box is flat in any dimension using the default precision. The following code shows how to create a box: ~~~~{.cpp} -TopoDS_Solid aBox = BRepPrimAPI_MakeBox(10.,20.,30.); +TopoDS_Solid aBox = BRepPrimAPI_MakeBox(10.,20.,30.); ~~~~ The four methods to build a box are shown in the figure: @@ -1554,7 +1554,7 @@ The following code builds the solid cone of the figure, which is located in the ~~~~{.cpp} double R1 = 30, R2 = 10, H = 15; -TopoDS_Solid S = BRepPrimAPI_MakeCone(R1,R2,H); +TopoDS_Solid S = BRepPrimAPI_MakeCone(R1,R2,H); ~~~~ @figure{/user_guides/modeling_algos/images/modeling_algos_image030.png,"Cone",360} @@ -1653,11 +1653,11 @@ double l = 10; // create a vector from the direction and the length gp_Vec v = direc; v *= l; -TopoDS_Solid P1 = BRepPrimAPI_MakePrism(F,v); +TopoDS_Shape P1 = BRepPrimAPI_MakePrism(F,v).Shape(); // finite -TopoDS_Solid P2 = BRepPrimAPI_MakePrism(F,direc); +TopoDS_Shape P2 = BRepPrimAPI_MakePrism(F,direc).Shape(); // infinite -TopoDS_Solid P3 = BRepPrimAPI_MakePrism(F,direc,false); +TopoDS_Shape P3 = BRepPrimAPI_MakePrism(F,direc,false).Shape(); // semi-infinite ~~~~ diff --git a/dox/user_guides/modeling_data/modeling_data.md b/dox/user_guides/modeling_data/modeling_data.md index 842ed565dd..60e1b1b31d 100644 --- a/dox/user_guides/modeling_data/modeling_data.md +++ b/dox/user_guides/modeling_data/modeling_data.md @@ -645,7 +645,7 @@ TopAbs contains the *TopAbs_ShapeEnum* enumeration, which lists the different to A topological model can be considered as a graph of objects with adjacency relationships. When modeling a part in 2D or 3D space it must belong to one of the categories listed in the ShapeEnum enumeration. -The TopAbspackage lists all the objects, which can be found in any model. +The TopAbs package lists all the objects, which can be found in any model. It cannot be extended but a subset can be used. For example, the notion of solid is useless in 2D. The terms of the enumeration appear in order from the most complex to the most simple, because objects can contain simpler objects in their description. @@ -1105,7 +1105,7 @@ One solution is to put all the Shapes in a Map so as to avoid counting them twic } ~~~~ -**Note** For more details about Maps, refer to the *TCollection* documentation (Foundation Classes Reference Manual). +**Note** For more details about Maps, refer to the *NCollection* documentation (Foundation Classes Reference Manual). The following example is more ambitious and writes a program which copies a data structure using an *IndexedMap*. The copy is an identical structure but it shares nothing with the original. diff --git a/dox/user_guides/shape_healing/shape_healing.md b/dox/user_guides/shape_healing/shape_healing.md index 5935388be1..90c7d53137 100644 --- a/dox/user_guides/shape_healing/shape_healing.md +++ b/dox/user_guides/shape_healing/shape_healing.md @@ -842,7 +842,7 @@ if (aCheckEdge.CheckOverlapping (theEdge1, theEdge2, aTolOverlap, theDomainDist) @subsubsection occt_shg_3_1_4 Analysis of presence of small faces -Class *ShapeAnalysis_CheckSmallFace* class is intended for analyzing small faces from the shape using the following methods: +*ShapeAnalysis_CheckSmallFace* class is intended for analyzing small faces from the shape using the following methods: * *CheckSpotFace()* checks if the size of the face is less than the given precision; * *CheckStripFace* checks if the size of the face in one dimension is less than the given precision. @@ -1090,7 +1090,7 @@ aShDivCont.SetSurfaceCriterion(GeomAbs_C2); aShDivCont.Perform(); // check the status and gets the result -if (aShDivCont.Status (ShapeExtend_DONE) +if (aShDivCont.Status (ShapeExtend_DONE)) { TopoDS_Shape aResult = aShDivCont.GetResult(); } @@ -1157,7 +1157,7 @@ for (TopExp_Explorer anExp (anInitShape, TopAbs_FACE); anExp.More(); anExp.Next( Class *ShapeUpgrade_ShapeDivide* provides shape splitting and converting according to the given criteria. It performs these operations for each face with the given tool for face splitting (*ShapeUpgrade_FaceDivide* by default). -This tool provides access to the tool for dividing faces with the help of the methods *SetSplitFaceTool* and *GetSpliFaceTool.* +This tool allows setting the tool for dividing faces with the help of the method *SetSplitFaceTool*. @subsubsection occt_shg_4_2_2 General tool for face splitting @@ -1183,7 +1183,7 @@ If the 3D curve is split then the 2D curve on the face is split as well, and vic The original shape is not modified. Modifications made are recorded in the context (*ShapeBuild_ReShape*). This tool provides access to the tool for dividing and splitting 3D and 2D curves by means of the following methods: -* *SetEdgeDivdeTool*, +* *SetEdgeDivideTool*, * *GetEdgeDivideTool*, * *SetSplitCurve3dTool*, * *GetSplitCurve3dTool*, @@ -1594,7 +1594,7 @@ aTool->Perform (theSeqShapes); // when method Perform is carried out on whole shape aTool->Perform(); // check status set after method Perform -if (aTool->Status (ShapeExtend_FAIL) +if (aTool->Status (ShapeExtend_FAIL)) { std::cout << "Operation failed\n"; return; @@ -1973,8 +1973,8 @@ This operator can be called with the following parameters: * *Boolean : Curve2dMode* allows considering the 2d curves; * *Real : Tolerance3d* defines 3d tolerance to be used in computation; * *Real : Tolerance2d* defines 2d tolerance to be used when computing 2d curves; -* *GeomAbs_Shape (C0 G1 C1 G2 C2 CN) : Continuity3d* is the continuity required in 2d; -* *GeomAbs_Shape (C0 G1 C1 G2 C2 CN) : Continuity2d* is the continuity required in 3d; +* *GeomAbs_Shape (C0 G1 C1 G2 C2 CN) : Continuity3d* is the continuity required in 3d; +* *GeomAbs_Shape (C0 G1 C1 G2 C2 CN) : Continuity2d* is the continuity required in 2d; * *Integer : RequiredDegree* gives the required degree; * *Integer : RequiredNbSegments* gives the required number of segments; * *Boolean : PreferDegree* if true, *RequiredDegree* has a priority, else *RequiredNbSegments* has a priority; diff --git a/dox/user_guides/step/step.md b/dox/user_guides/step/step.md index 7c8619b8a9..d1f836b660 100644 --- a/dox/user_guides/step/step.md +++ b/dox/user_guides/step/step.md @@ -30,7 +30,7 @@ Beyond the upper level API, which is fitted for an easy end-use, the STEP exchan * Specific packages for Data definition and checking; * Physical Access supported by Drivers (Part 21 file access is embedded); -* Conversion to/from Open Cascade or applicative data supported by drivers (OCC-BREP and XDE ard basically provided); +* Conversion to/from Open Cascade or applicative data supported by drivers (OCC-BREP and XDE are basically provided); * Tools for analysis, filtering, etc... including DRAW commands. These modules share common architecture and capabilities with other exchange modules of Open Cascade, like Shape Healing. @@ -739,8 +739,8 @@ Not all entities defining the assembly structure in the STEP file are translated | | composite_curve | TopoDS_Wire | | | | composite_curve_on_surface | TopoDS_Wire | | | | boundary_curve | TopoDS_Wire | | -| Surfaces | b_spline_surface | Geom_BsplineSurface | | -| | b_spline_surface_with_knots | Geom_BsplineSurface | | +| Surfaces | b_spline_surface | Geom_BSplineSurface | | +| | b_spline_surface_with_knots | Geom_BSplineSurface | | | | bezier_surface | Geom_BSplineSurface | | | | conical_surface | Geom_ConicalSurface | | | | cylindrical_surface | Geom_CylindricalSurface | | @@ -832,7 +832,7 @@ The following default tolerances are used when creating shapes and how they are

Healing of resulting shape in ShapeHealing component

##### ShapeFix_Wire::FixSelfIntersection() -This method is intended for detecting and fixing self-intersecting edges and intersections of adjacent edges in a wire. It fixes self-intersections by cutting edges at the intersection point and/or by increasing the tolerance of the vertex (so that the vertex comprises the point of intersection). There is a maximum tolerance that can be set by this method transmitted as a parameter, currently is *read.maxprecision.value*. +This method is intended for detecting and fixing self-intersecting edges and intersections of adjacent edges in a wire. It fixes self-intersections by cutting edges at the intersection point and/or by increasing the tolerance of the vertex (so that the vertex comprises the point of intersection). There is a maximum tolerance that can be set by this method transmitted as a parameter, currently is *read.maxprecision.val*. When a self-intersection of one edge is found, it is fixed by one of the two methods: * tolerance of the vertex of that edge which is nearest to the point of self-intersection is increased so that it comprises both its own old position and the intersection point @@ -1198,8 +1198,8 @@ The table below describes STEP entities, which are created when the assembly str | | Geom_OffsetSurface | offset_surface | | | | Geom_RectangularTrimmedSurface | rectangular_trimmed_surface | | | | Geom_SphericalSurface | spherical_surface | | -| | Geom_SurfaceOfLinear Extrusion | surface_of_linear_extrusion | | -| | Geom_SurfaceOf Revolution | surface_of_revolution | | +| | Geom_SurfaceOfLinearExtrusion | surface_of_linear_extrusion | | +| | Geom_SurfaceOfRevolution | surface_of_revolution | | | | Geom_ToroidalSurface | toroidal_surface or degenerate_toroidal_surface | *degenerate_toroidal_surface* is produced if the minor radius is greater than the major one | | | Geom_BezierSurface | b_spline_surface_with_knots | | | | Geom_BSplineSurface | b_spline_surface_with_knots or rational_b_spline_surface | *rational_b_spline_surface* is produced if *Geom_BSplineSurface* is a rational BSpline | @@ -1463,7 +1463,7 @@ Entities in the STEP file are numbered in the succeeding order. An entity can be Information about product names, *next_assembly_usage_occurrence, shape_definition_representation, context_dependent_shape_representation* or *mapped_item entities* that are involved into the assembly structure will be printed. @subsubsection occt_step_6_4_2 Estimating the results of reading STEP -All the following commands are available only after data is converted into OCCT shapes (i.e. after command 214read). +All the following commands are available only after data is converted into OCCT shapes (i.e. after command stepread). Command *Draw:> tpstat [*|?]\ [\]* is provided to get all statistics on the last transfer, including a list of transferred entities with mapping from STEP to OCCT types, as well as fail and warning messages. The parameter \ defines what information will be printed: @@ -1777,4 +1777,3 @@ Saved Views are not exported by OCCT. ### User defined attributes Attributes can be imported from STEP. - diff --git a/dox/user_guides/visualization/visualization.md b/dox/user_guides/visualization/visualization.md index 54089f7246..18380af9bf 100644 --- a/dox/user_guides/visualization/visualization.md +++ b/dox/user_guides/visualization/visualization.md @@ -194,7 +194,7 @@ For example, the *AIS_Shape* object determine the following modes (see AIS_Shape #### Viewer selector -For each OCCT viewer there is a **Viewer selector** class *SelectMgr_ViewerSelector3d*. +For each OCCT viewer there is a **Viewer selector** class *SelectMgr_ViewerSelector*. It provides a high-level API for the whole selection algorithm and encapsulates the processing of objects and sensitive entities for each mouse pick. The viewer selector maintains activation and deactivation of selection modes, launches the algorithm, which detects candidate entities to be picked, and stores its results, as well as implements an interface for keeping selection structures up-to-date. @@ -238,7 +238,7 @@ To maintain selection mechanism at the viewer level, a speedup structure compose The first level tree is constructed of axis-aligned bounding boxes of each selectable object. Hence, the root of this tree contains the combination of all selectable boundaries even if they have no currently activated selections. Objects are added during the display of *AIS_InteractiveObject* and will be removed from this tree only when the object is destroyed. -The 1st level BVH tree is build on demand simultaneously with the first run of the selection algorithm. +The 1st level BVH tree is built on demand simultaneously with the first run of the selection algorithm. The second level BVH tree consists of all sensitive entities of one selectable object. The 2nd level trees are built automatically when the default mode is activated and rebuilt whenever a new selection mode is calculated for the first time. @@ -898,7 +898,7 @@ theCtx->SetDisplayMode (2, true); // theObj1 stays visualized in its mode 3 ~~~~ -*PrsMgr_PresentationManager* and *SelectMgr_ViewerSelector3d*, which manage the presentation and selection of present interactive objects, are associated to the main Viewer. +*PrsMgr_PresentationManager* and *SelectMgr_ViewerSelector*, which manage the presentation and selection of present interactive objects, are associated to the main Viewer. @warning Do NOT use integer values (like in sample above) in real code - use appropriate enumerations instead! Each presentable object has independent list of supported display and selection modes; for instance, *AIS_DisplayMode* enumeration is applicable only to *AIS_Shape* presentations. @@ -1585,7 +1585,7 @@ aView->FitAll(); View projection and orientation in OCCT *V3d_View* are driven by camera. The camera calculates and supplies projection and view orientation matrices for rendering by OpenGL. -The allows to the user to control all projection parameters. +This allows the user to control all projection parameters. The camera is defined by the following properties: * **Eye** -- defines the observer (camera) position. diff --git a/dox/user_guides/xde/xde.md b/dox/user_guides/xde/xde.md index 664dd2916f..b9762bbb02 100644 --- a/dox/user_guides/xde/xde.md +++ b/dox/user_guides/xde/xde.md @@ -137,7 +137,7 @@ XDE provides capabilities for adding, editing and removing clipping planes. XDE supports reading from STEP views. Views allow saving information about camera parameters (position, direction, zoom factor, etc.) and visible shapes, PMIs, used clipping planes and notes. -Currently, XDE supports saving of clipping planes in XBF format only. +Currently, XDE supports saving of views in XBF format only. XDE provides the following view management capabilities: * add/remove views;