View Issue Details

IDProjectCategoryView StatusLast Update
0032668Open CASCADEOCCT:Documentationpublic2022-01-22 12:40
Reporterkgv Assigned Tobugmaster  
PrioritynormalSeverityfeature 
Status verifiedResolutionopen 
Target Version7.7.0 
Summary0032668: Documentation - add tutorial for creating a custom AIS Interactive Object
DescriptionTutorials section lacks articles introducing AIS to end users:
https://dev.opencascade.org/doc/overview/html/samples.html
- Tutorials and Demos
  * Novice Guide
  * Draw: Demo Scripts
  * Modeling: Bottle Tutorial
  * OCAF: Usage Tutorial
  * OCAF: Function Mechanism

Currently, there is a User's Guide document highlighting only technical aspects of OCCT Visualization and sharing a couple of code snippets:
https://dev.opencascade.org/doc/overview/html/occt_user_guides__visualization.html
https://dev.opencascade.org/doc/overview/html/occt_user_guides__visualization.html#occt_visu_4_5

It is proposed extending documentation with dedicated tutorial-alike (e.g. learning step-by-step some subject) articles for writing AIS interactive objects at application level:
- AIS: computing presentation;
- AIS: computing selection.

It is also desired revising Visualization User's Guide structure, but this could be done in scope of a dedicated issue.
Steps To ReproduceN/A
TagsNo tags attached.
Test case numberdemo samples aisobject

Activities

git

2022-01-14 15:41

administrator   ~0106367

Branch CR32668 has been created by kgv.

SHA-1: a81726929acdcc1249e2069618a18f3bf455f8d2


Detailed log of new commits:

Author: kgv
Date: Thu Jan 13 15:51:40 2022 +0300

    0032668: Documentation - add tutorial for creating a custom AIS Interactive Object

git

2022-01-14 17:37

administrator   ~0106370

Branch CR32668_1 has been created by kgv.

SHA-1: 7b8896a1c4db55b85c219d8857612232bc340268


Detailed log of new commits:

Author: kgv
Date: Thu Jan 13 15:51:40 2022 +0300

    0032668: Documentation - add tutorial for creating a custom AIS Interactive Object

git

2022-01-14 18:35

administrator   ~0106374

Branch CR32668_1 has been updated forcibly by kgv.

SHA-1: 779891abadce2b5dff82d2cce435c154cbe1a46a

git

2022-01-14 18:38

administrator   ~0106375

Branch CR32668_1 has been updated forcibly by kgv.

SHA-1: 7982006cd4b5c4940833ca8a46e2ca02b4c24339

git

2022-01-14 18:44

administrator   ~0106377

Branch CR32668_1 has been updated forcibly by kgv.

SHA-1: 605386ed99eedc81e8d9f1df25e31af1607aaf7b

git

2022-01-14 18:46

administrator   ~0106378

Branch CR32668_1 has been updated forcibly by kgv.

SHA-1: 76537b705762384762bd246b97ba078126b9ceef

git

2022-01-14 20:08

administrator   ~0106379

Branch CR32668_1 has been updated forcibly by kgv.

SHA-1: 9856e7c5b8727e27df9a948e79291aed30153c73

kgv

2022-01-14 20:09

developer   ~0106380

Patch is ready for review
- OCCT: branch CR32668_1.

http://jenkins-test-occt.nnov.opencascade.com/view/CR32668_1-master-KGV/

git

2022-01-18 11:10

administrator   ~0106434

Branch CR32668_1 has been updated forcibly by kgv.

SHA-1: c22b3ba3f32f4f3af0aca7b77052e0c043f007e0

aml

2022-01-18 12:32

developer   ~0106435

1. QADraw_Tutorials.cxx - misprint in the header:

// Created on: 2002-02-04
// Created by: QA Admin
// Copyright (c) 2002-2014 OPEN CASCADE SAS

2. QADraw_Tutorials.cxx::72 - Extend intro comment. Let's explicitly indicate that commented lines are not dead code; they are commented and uncommented when progessing frogh the tutorial.

3. QADraw_Tutorials.cxx::95 - wrong indent.

4. QADraw_Tutorials.cxx::99-100 - inconsitent spacing. No space after `NewGroup` and space after `SetGroupPrimitivesAspect.` To be honest, no spacing looks more preferable for me.

Handle(Graphic3d_Group) aGroupTris = thePrs->NewGroup();
aGroupTris->SetGroupPrimitivesAspect (myDrawer->ShadingAspect()->Aspect());

5. QADraw_Tutorials.cxx::131-137 - inconsistent handling of empty line. Sometimes, there is an empty line after a method. Sometimes, not. For me, readability is better when there is always an empty line.

6. QADraw_Tutorials.cxx::158, 271 - auto usage. Please avoid `auto` usage. It is a holywar topic, but in tutorial it is even more important to see actual type. Moreover, on line 271 you have a memory leak :).

7. ais_object.md::66, 183, 189 - add empty lines around "..." to improve readability.

8. ais_object.md::79-80 - extend info about absence of default value of display mode, Typical values, etc.

9. ais_object.md::131,171 - `+` should be with spaces. Also, it is `Result of ... presentation builder` but not builders themselves.

"@c StdPrs_ShadedShape+StdPrs_WFShape presentation builders."

10. ais_object.md::255 - Display model transparent to see all three edges in section.

I know that we haven't covered this topic at that stage of tutorial, but reader may frustrate from setting 3 edges and seeing only 2 of them.

11. ais_object.md::277 - Awkward phrase "defined for as specializations for a specific primitive array type"

To my mind, it should be "defined as specializations for a specific primitive array type"

12. ais_object.md::360 - default -> original

13. ais_object.md::405 - Please explain why. Number of draw calls in underlying OpenGL driver is limited and it is safer to have small number of draw calls with huge primitive arrays to display. Something like this. I guess, you know the right words better than me ;)

14. ais_object.md::405 - "in A similar way"

15. ais_object.md::480 - the user -> a user "But inconsistency between presentation and selection might confuse the user"

16. ais_object.md::495 - Application -> A user "Application should be careful to activate only the modes that actually make sense and may work together."

17. ais_object.md::575 - "Default SelectMgr_EntityOwner::HilightWithColor()." -> Default behavior of SelectMgr_EntityOwner::HilightWithColor().

18. ais_object.md::600 - "Custom MyAisOwner::HilightWithColor()" -> "Result of custom implementation MyAisOwner::HilightWithColor()"

git

2022-01-18 13:01

administrator   ~0106436

Branch CR32668_1 has been updated by kgv.

SHA-1: 9010444d80704138e704ae29eadf456c786d86d7


Detailed log of new commits:

Author: kgv
Date: Tue Jan 18 12:51:27 2022 +0300

    # remarks

kgv

2022-01-18 13:04

developer   ~0106437

Last edited: 2022-01-18 13:04

> 10. ais_object.md::255 - Display model transparent to see all three edges in section.
> I know that we haven't covered this topic at that stage of tutorial, but reader may frustrate from setting 3 edges and seeing only 2 of them.
User will see all edges by rotating the camera - transparency is not needed here.

> 3. QADraw_Tutorials.cxx::95 - wrong indent.
Haven't been able to identify this piece.

git

2022-01-18 13:52

administrator   ~0106438

Branch CR32668_2 has been created by kgv.

SHA-1: 86447d2127cf8ac67fb7f70b6ec5c906e9205f38


Detailed log of new commits:

Author: kgv
Date: Thu Jan 13 15:51:40 2022 +0300

    0032668: Documentation - add tutorial for creating a custom AIS Interactive Object

aml

2022-01-18 18:59

developer   ~0106454

Last edited: 2022-01-18 19:06

1. "Let's extend our sample and display a cylinder section contour defined by array of indexed segments (e.g. a polyline of three vertices):"

After replacement by cylinder our polyline consists of 4 vertices. Please take a look and change the wording related to this modification.

2. Add a link from .md document with the tutorial to the file with a complete source code. Currently, we have the link: code -> doc. One can add a phrase at the tutorial's beginning: "The complete source code related to this tutorial can be found ..." Having both references will decrease the probability of non-coherent modifications. Thank you.

git

2022-01-18 19:09

administrator   ~0106455

Branch CR32668_2 has been updated by kgv.

SHA-1: 8f84af53b5d9e2b82e449c0c2ee464344bd9fcd3


Detailed log of new commits:

Author: kgv
Date: Tue Jan 18 15:28:02 2022 +0300

    0032783: Documentation - Doxygen 1.9.3 generates corrupted HTML for dox/samples/ocaf.md
    
    Fix incorrect/fragile Markdown syntax in samples/ocaf and user_guides/modeling_data.

git

2022-01-18 19:15

administrator   ~0106456

Branch CR32668_2 has been updated forcibly by kgv.

SHA-1: 70a85b229d81c8dafcc4cb0aef4614caaba537d3

kgv

2022-01-18 19:15

developer   ~0106457

Patch has been updated.

aml

2022-01-18 19:22

developer   ~0106458

Please raise the patch.

OCCT: CR32668_2
Products: -

smoskvin

2022-01-22 11:46

administrator   ~0106519

Combination -
OCCT branch : IR-2022-01-21
master SHA - 5614b1369a232f43e59cb9be4f5f8efd2075608d
49e51745631c52b6c452c65adae4d6dfa21a1b1e
Products branch : IR-2022-01-21 SHA - 6c9eed61a7023644fdd1361491a49abf318c0d20
was compiled on Linux, MacOS and Windows platforms and tested in optimize mode.

Number of compiler warnings:
No new/fixed warnings

Regressions/Differences/Improvements:
No regressions/differences

CPU differences:
Debian80-64:
OCCT
Total CPU difference: 18406.870000000446 / 18505.100000000388 [-0.53%]
Products
Total CPU difference: 11642.890000000107 / 11656.240000000102 [-0.11%]
Windows-64-VC14:
OCCT
Total CPU difference: 20282.578125 / 20270.375 [+0.06%]
Products
Total CPU difference: 13127.640625 / 13139.84375 [-0.09%]


Image differences :
No differences that require special attention

Memory differences :
No differences that require special attention

git

2022-01-22 12:40

administrator   ~0106531

Branch CR32668 has been deleted by mnt.

SHA-1: a81726929acdcc1249e2069618a18f3bf455f8d2

git

2022-01-22 12:40

administrator   ~0106532

Branch CR32668_1 has been deleted by mnt.

SHA-1: 9010444d80704138e704ae29eadf456c786d86d7

git

2022-01-22 12:40

administrator   ~0106533

Branch CR32668_2 has been deleted by mnt.

SHA-1: 70a85b229d81c8dafcc4cb0aef4614caaba537d3

Related Changesets

occt: master ba9548c5

2022-01-13 15:51:40

kgv


Committer: smoskvin Details Diff
0032668: Documentation - add tutorial for creating a custom AIS Interactive Object Affected Issues
0032668
mod - dox/FILES_HTML.txt Diff File
add - dox/samples/ais_object.md Diff File
add - dox/samples/images/ais_object_step1_bndbox.png Diff File
add - dox/samples/images/ais_object_step1_highlight.png Diff File
add - dox/samples/images/ais_object_step1_shaded.png Diff File
add - dox/samples/images/ais_object_step1_shaded_wf.png Diff File
add - dox/samples/images/ais_object_step2_segments.png Diff File
add - dox/samples/images/ais_object_step3_quadrics_10.png Diff File
add - dox/samples/images/ais_object_step3_quadrics_25.png Diff File
add - dox/samples/images/ais_object_step3_quadrics_disk.png Diff File
add - dox/samples/images/ais_object_step3_quadrics_fin.png Diff File
add - dox/samples/images/ais_object_step4_highlight1.png Diff File
add - dox/samples/images/ais_object_step4_highlight2.png Diff File
add - dox/samples/images/ais_object_step4_highlight3.png Diff File
mod - dox/samples/samples.md Diff File
mod - src/QADraw/FILES Diff File
mod - src/QADraw/QADraw.cxx Diff File
mod - src/QADraw/QADraw.hxx Diff File
rm - src/QADraw/QADraw_Additional.cxx Diff File
add - src/QADraw/QADraw_Tutorials.cxx Diff File
add - tests/demo/samples/aisobject Diff File

Issue History

Date Modified Username Field Change
2021-11-17 09:38 kgv New Issue
2021-11-17 09:38 kgv Assigned To => kgv
2022-01-14 15:41 git Note Added: 0106367
2022-01-14 17:37 git Note Added: 0106370
2022-01-14 18:35 git Note Added: 0106374
2022-01-14 18:38 git Note Added: 0106375
2022-01-14 18:44 git Note Added: 0106377
2022-01-14 18:46 git Note Added: 0106378
2022-01-14 20:08 git Note Added: 0106379
2022-01-14 20:09 kgv Assigned To kgv => aml
2022-01-14 20:09 kgv Status new => resolved
2022-01-14 20:09 kgv Test case number => demo samples aisobject
2022-01-14 20:09 kgv Note Added: 0106380
2022-01-18 11:10 git Note Added: 0106434
2022-01-18 12:32 aml Assigned To aml => kgv
2022-01-18 12:32 aml Status resolved => assigned
2022-01-18 12:32 aml Note Added: 0106435
2022-01-18 13:01 git Note Added: 0106436
2022-01-18 13:04 kgv Note Added: 0106437
2022-01-18 13:04 kgv Note Edited: 0106437
2022-01-18 13:05 kgv Assigned To kgv => aml
2022-01-18 13:05 kgv Status assigned => resolved
2022-01-18 13:52 git Note Added: 0106438
2022-01-18 18:59 aml Assigned To aml => kgv
2022-01-18 18:59 aml Status resolved => assigned
2022-01-18 18:59 aml Note Added: 0106454
2022-01-18 19:01 aml Note Edited: 0106454
2022-01-18 19:06 aml Note Edited: 0106454
2022-01-18 19:09 git Note Added: 0106455
2022-01-18 19:15 git Note Added: 0106456
2022-01-18 19:15 kgv Assigned To kgv => aml
2022-01-18 19:15 kgv Status assigned => resolved
2022-01-18 19:15 kgv Note Added: 0106457
2022-01-18 19:22 aml Assigned To aml => bugmaster
2022-01-18 19:22 aml Status resolved => reviewed
2022-01-18 19:22 aml Additional Information Updated
2022-01-18 19:22 aml Note Added: 0106458
2022-01-18 19:22 aml Additional Information Updated
2022-01-19 10:40 kgv Time allocated 18.1.2022: 2 h. => set
2022-01-22 11:46 smoskvin Status reviewed => tested
2022-01-22 11:46 smoskvin Note Added: 0106519
2022-01-22 12:09 smoskvin Changeset attached => occt master ba9548c5
2022-01-22 12:28 bugmaster Status tested => verified
2022-01-22 12:40 git Note Added: 0106531
2022-01-22 12:40 git Note Added: 0106532
2022-01-22 12:40 git Note Added: 0106533