RFC: generating the PTZ specs with Github actions

[ocampana-videotec]

As we are all aware, the PTZ Service specs cannot be generated with the same tools as for the other documents, but we have to rely on an external editor.

To allow generating the documents with Github actions, while preserving the possibility to edit the equations without a graphic editor, in this PR I propose to use intermediate .svg files generated form MathML, so that the pdf for the PTZ service can be generated.

Workflow

1. The user creates a .xml file under doc/equations, like this one
2. The user commits and pushes the file, so that Github actions can generated the correspondent .svg file
3. The user pull the file from the repo and uses it normaly, as any other image.

[willysagefalk]

Looks good 👍
The SVG renders fine for me, and the GitHub Actions approach feels like a practical way to handle PTZ equations

[venki5685]

when I open in ptz spec document from ""tc/compile_ptz_service"in browser. It appears like below.

[ocampana-videotec]

when I open in ptz spec document from ""tc/compile_ptz_service"in browser. It appears like below.

That has not been touched yet. The first commit only changed 5.7.1.4 Zoom position space in millimeters to show the proposed workflow.

[kieran242]

5.7.1.4

if these are the formulas that you are referring to then it renders well. I have seen what @venki5685 reported and was concerned until I read your response.

[ocampana-videotec]

I am observing the rendered content at this URL.

None of the formulas seem to render correctly, neither if the SVG or with embedded MathML

The equation surrounded with the red box is the one I changed, that should show this svg image

But the equation in the green box is broken as well, and this has not being touched by my proposal.

[kieran242]

I am observing the rendered content at this URL.

None of the formulas seem to render correctly, neither if the SVG or with embedded MathML

The equation surrounded with the red box is the one I changed, that should show this [svg image](https://github.com/onvif/specs/blob/tc/compile_ptz_service/doc/equations/PTZ/zoom_magnification_from_focal_length.svg)

But the equation in the green box is broken as well, and this has not being touched by my proposal.

still a bit to look into then :)

[ocampana-videotec]

Small update. the online preview still has the the old code with embedded MathML. I am trying to understand why it did not update. (I rebased to squash branch to have just one commit, this may be the reason why it is not updating any more)

[mfournier-genetec]

With the laterst PR it looks good on my side

[ocampana-videotec]

So, sync was broken and xml needed enhancement as well.

Here is it how it looks like now online, where the equations with the red frame are those fixed by me and the green one is untouched and still broken because of MathML embedded in the xml spec file:

And this is how it looks like when exporting the PDF from author

I think that with this proposal we get better readability online when developing new specs. The size of the images has still to be twicked.

[mfournier-genetec]

typo --> folder

[kieran242]

@ocampana-videotec I am seeing no page separation , document contents and the Formulas not rendering. I was comparing the 25.06 PTZ Spec with the Generated on on the Dev Rendering.

Should I be looking at a different doc?

[ocampana-videotec]

@ocampana-videotec I am seeing no page separation , document contents and the Formulas not rendering. I was comparing the 25.06 PTZ Spec with the Generated on on the Dev Rendering.

Should I be looking at a different doc?

The formulas should be a bit lower than that image, try to scroll down to §5.7.1.4.

About the page breaks: they are never present when you look at the branches on developer.onvif.org . They are added when generating the PDF file.

[kieran242]

@ocampana-videotec I am seeing no page separation , document contents and the Formulas not rendering. I was comparing the 25.06 PTZ Spec with the Generated on on the Dev Rendering.
Should I be looking at a different doc?

The formulas should be a bit lower than that image, try to scroll down to §5.7.1.4.

About the page breaks: they are never present when you look at the branches on developer.onvif.org . They are added when generating the PDF file.

Sorry @ocampana-videotec this is a screen shot from 25.06 containing formulas on that page and on the 25.12 version has them also (I take it that version was generated in the old way.)

r-attachments/assets/28a7cd6b-02bc-47a6-a0b9-7eed262fea19" /> t; />

[ocampana-videotec]

I completed updating all the equations in the document. There is still pending the choice of the size of the equations. which is purely cosmetical and I think we can defer this to our next F2F meeting.

Please, review both the online preview on developer.onvif.org and the attached generated file (it does not have the draft watermark, to avoid rendering issues)

ONVIF-PTZ-Service-Spec-PR700.pdf

Beyond the cosmetical issue, for me it is ready for inclusion in 26.06

[HansBusch]

Propose to defer the change to 26.06 and generate the 25.12 document using oxygen. The formula rendering looks nice but the large size and position issues make most very hard to read.

[ocampana-videotec]

Propose to defer the change to 26.06 and generate the 25.12 document using oxygen. The formula rendering looks nice but the large size and position issues make most very hard to read.

I fully agree, in fact this PR is tagged 26.06 , to have the time to agree on the appearance of the formulas.

[kieran242]

@ocampana-videotec approved with discussion and review in TC meeting