Content Document, 6.4.2., ICB in SVG

[iherman]

The text says:

...otherwise, the [SVG] height and width attributes SHOULD be used.

I am not sure how this would work in practice. Indeed, height can be used, in SVG, to set absolute values. Eg, I could say height=104cm and the idea is that the drawing is 105cm high. If that is the only dimension value for the SVG content, what should be the behaviour of the RS?

[mattgarrish]

The RS will take a best guess at the aspect ratio as described in the next statement, no? Whatever it decides it will use to scale the image.

I don't think we want to delve into the fuzziness of how the guess is made, but adding @rkwright in case he has other thoughts on this.

[iherman]

The problem is not the aspect ratio. The problem is that, per SVG, the hight and width of the drawing is supposed to be taken literally in case it is expressed with real metric values. As far as I know, SVG agent in, say, a browser are supposed to make a best guess as for the size of the screen, clip the image on that screen and, possibly, provide panning to move around the image.

But my SVG is rusty, this may have changed. See what Ric (or Luc?) have to say.

Cc: @rkwright

[rkwright]

Hm. I guess I am not sure what the concern here is. IIRC correctly, the intent was that if the height and width were specified in concrete units, then the user agent was supposed to render it at that size as near as the user agent knew. So, as far as I know, Ivan is correct that the user agent should try to render the content at the specified size. If it is too big it should be clipped to the box (see here).

[iherman]

Hm. I guess I am not sure what the concern here is. IIRC correctly, the intent was that if the height and width were specified in concrete units, then the user agent was supposed to render it at that size as near as the user agent knew. So, as far as I know, Ivan is correct that the user agent should try to render the content at the specified size. If it is too big it should be clipped to the box (see here https://www.w3.org/TR/SVG/masking.html#InitialClippingPath).

I must admit that, after re-reading it, I indeed do not see any mistakes in the text. Maybe what triggered my issue is that I did not see whether the possibility to display a clipped version of an SVG slide really makes sense in this setting. While I believe that, for fixed layout purposes at least, using height and with with physical dimensions is not really useful, you are right that it is not, spec-wise, an error.

However… I always found that the interplay between the user agent, the value of viewBox, width and height, and how these are then used to display what part of a drawing, is one of the most complex things in SVG. (I remember having made tutorials that included this stuff as well, but I forgot all about it…) While the section on HTML gives some more explanation for the usage of the dimensions, there is essentially nothing for SVG, the example covers the most obvious (and probably most useful case only). Maybe it would be useful to provide some more examples to draw attention to different cases. As an example, to come back to the physical dimensions, show an example whereby an SVG drawing is defined in, say, centimeters, and emphasize that, in that case, what is displayed on a phone will be different than what is displayed on a tablet, due to the difference of physical display size. It is also a question on how a drawing will be displayed if the aspect ratio of a viewBox are different than the aspect ratio of the screen, how will that be displayed, etc.

Ric, you may have some examples around from your tests that could be reused...

[mattgarrish]

Were you keying in on this statement by any chance?

For both HTML and SVG Content Documents, the dimension expressions define the CSS initial containing block (ICB) in CSS Pixels [CSS 2.1].

This statement isn't true unless we limit the height and width to pixels for SVG Content Documents (but wouldn't apply to embedded SVG).

[iherman]

I do not remember how my mind exactly worked at that point (you know, the warranty is off over 60:-) but yes, that is indeed unclear what the intention was/is for that case. On the other hand, if I remember well (@rkwright should know that much better than I do) the idea is that the SVG player has an estimate for the physical size of a display based on the characteristics of the device, the pixel sizes, etc, and then makes an approximate mapping from the physical size to display pixels. That should be defined somewhere... But, if so, then this statement is not necessarily in contradiction with the usage of physical dimensions.

But... as this discussion shows, there is a gray area here that deserves some explanation in the text. If we are messed up, I would expect others (with a few exception) be messed up, too.

[mattgarrish]

Right, the statement previously made sense because the viewport meta element and viewBox attribute didn't allow unit values.

Since we've added the height and width attributes to the mix, it's unclear if that statement forces them to be pixels, or, as you say, whether there is an expectation the reading system will convert the values it finds.

[rkwright]

I kind of think we're making a mountain out of molehill here. I would argue that the only real useful case for a SVG to have concrete size specified (i.e. not 100%, 100% - which is the default) is when the SVG is being used as a standalone spine item. In all other cases, I would argue that one SHOULD use the default with an appropriate viewbox. Of course, people can do what they like, but I can't think of another use case for concrete dimensions for height and width that makes sense.

BTW, here is a sample file I put together (just renamed to .zip so github would accept it) that demonstrates various ways of using SVG (cover, spine, embedded, etc.). The last page has a height of 10 cm and a width of 5 cm. Sadly, Readium doesn't render the last page correctly. Both ReadiumJS and SDK have errors - different ones. Sigh, two more issues to file. iBooks on the desktop and Vital Source do it correctly. iBooks on the iPad makes a mess of several of the pages, including the last.

[iherman]

@rkwright, I do not see the zip file:-( Where is it?

B.t.w., I fully agree with your statement whereby:

In all other cases, I would argue that one SHOULD use the default with an appropriate viewbox

i.e., people should not use width and height in these cases. (Worth being added to the document.) Actually, even when SVG is a spine item: what is the real use? Isn't it true that, in that case, the SVG file would look different on different devices because it will be clipped differently? Do we want that?

[rkwright]

Sorry. Here it is. Tiny-SVG.zip

re your last question, the primary case I use (as demonstrated in the attached file (really, this time) is to render the SVG without having to wrap it in an HTML file. It's really not a big deal one way or the other. I do it more because it's allowed per spec and I like to verify that Readium, at least, does it correctly. In fact, IIRC, Readium sees the SVG spine item and wraps it in an HTML anyway. I'll check on that later.

As for looking different on different devices, in theory that is true, but Readium, like other RS', sort of cheats and scales fixed size pages to the size of the enclosing container.

[mattgarrish]

The ICB calculation is only for SVG Content Documents referenced from the spine (fixed layouts). These requirements don't apply to embedded SVG.

The first paragraph in 6.4 also needs to change. It currently states:

Each EPUB Content Document referenced from a spine item that has the pre-paginated value set must contain the viewport (for HTML) or viewBox (for SVG) dimension expressions as defined below.

I guess we can drop this entirely, since viewport is required in the html section and the svg no longer requires dimensions to be set.

[iherman]

On 22 Aug 2016, at 16:22, Ric Wright notifications@github.com wrote:

Sorry. Here it is. Tiny-SVG.zip https://github.com/IDPF/epub-revision/files/430346/Tiny-SVG.zip re your last question, the primary case I use (as demonstrated in the attached file (really, this time) is to render the SVG without having to wrap it in an HTML file. It's really not a big deal one way or the other. I do it more because it's allowed per spec and I like to verify that Readium, at least, does it correctly. In fact, IIRC, Readium sees the SVG spine item and wraps it in an HTML anyway. I'll check on that later.

As for looking different on different devices, in theory that is true, but Readium, like other RS', sort of cheats and scales fixed size pages to the size of the enclosing container.

If I look at the last svg in your file (which is a spine element in the EPUB file) but I simply look at the file in Firefox, then Firefox displays, on my screen, the rectangle roughly 5 x 10cm, and if I change the window, the drawing remains, essentially, unchanged, though it is possibly clipped if I make the window very small. I believe that is the right behaviour. In other words, if Readium, but also iBook reader on my laptop, tries indeed to reduce it in size (and then something strange happens on ibook, it disappears) if I reduce the reader's dimension. I would think that that behaviour is, actually not correct per the SVG spec.

You use 'px' in your other SVG documents; SVG refers to CSS on what that means, and the CSS spec says it is relative to the device. In other words, px is not an absolute measure. Those files rescale with the display, and that is correct. Whether width and height is useful for those cases even if the SVG file is standalone spine: I am not sure. They are not harmful.

But, in my view, absolute measures, like mm, cm, km, etc, are absolutely useless in an EPUB setting because they DO look different on different devices. If so, I believe we may want to put an explicit statement into the document that authors should not use those measures… And, actually, they should probably stick to the usage of viewBox only, as you said…

Ivan

[mattgarrish]

To try and get this wrapped up, what about dropping the first two paragraphs in 6.4 and inserting a new 6.2 Content Conformance section that states:

A conformant Fixed Layout Document MUST meet the following requirements:

• It MUST specify its initial containing block (ICB) [CSS 2.1] as defined in 6.5.

This will give better symmetry with other sections that state their content and RS requirements upfront.

We can then add the following statement after the XHTML viewport example:

The dimension expressions in the viewport meta tag define the ICB in CSS Pixels [CSS 2.1].

We can then also drop this bullet from the Packages specification: "For fixed layouts expressed using the rendition:layout property, it must determine the rendering dimensions as defined in Fixed Layouts [Content Docs 3.1]." This is covered in the rendition:layout definition and this specification.

[GarthConboy]

Conceptually good.

Does "The dimension expressions in the viewBox meta define..." want to be "The dimension expressions in the viewBox attribute define..."?

[mattgarrish]

Oops, yes, bad copy/paste.

[rkwright]

The SVG spec absolutely does not require that the viewbox dimensions are in pixels. Quite the opposite, in fact. Our (SVG WG) intent was to map the coordinates of the page which might be microns or parsecs to the actual rendering surface. Are we suggesting that it SHOULD be pixels? If so, why?

[mattgarrish]

The primary reason would be because that's the way fixed-layout svg documents are currently defined:

For both XHTML and SVG Content Documents, the dimension expressions define the CSS initial containing block (ICB) in CSS Pixels [CSS2.1].

This issue isn't about SVG embedded in xhtml content documents, or an SVG you don't mark as pre-paginated. These rules don't apply in those cases.

[iherman]

Actually… in practice (and I do not know per spec) the viewBox attribute is dimensionless. It defines the internal coordinate system that SVG content operates on; in the absence of the width and height attributes it is up to the user agent to create a mapping from that abstract coordinate space to the physical viewport. That means that this ICB will become the part of the window to which the viewBox can be mapped to, keeping its aspect ratio.

The bottom line is: I agree with Ric that there should be no mention of 'pixels' when referring to the viewBox. That what makes SVG scalable.

On 25 Aug 2016, at 21:38, Matt Garrish notifications@github.com wrote:

The primary reason would be because that's the way fixed-layout svg documents are currently defined:

For both XHTML and SVG Content Documents, the dimension expressions define the CSS initial containing block (ICB) in CSS Pixels [CSS2.1].

This issue isn't about SVG embedded in xhtml content documents, or an SVG you don't mark as pre-paginated. These rules don't apply in those cases.

[iherman]

To try and get this wrapped up, what about dropping the first two paragraphs in 6.4 and inserting a new 6.2 Content Conformance section that states:

A conformant Fixed Layout Document MUST meet the following requirements:

It MUST specify its CSS initial containing block (ICB) [CSS 2.1] as defined in 6.5. This will give better symmetry with other sections that state their content and RS requirements upfront.

We can then add the following statement after the XHTML viewport example:

The dimension expressions in the viewport meta tag define the ICB in CSS Pixels [CSS 2.1].

And in the SVG section change the first paragraph to:

For top-level SVG Content Documents, the ICB dimensions SHOULD be defined in the [SVG] viewBox attribute. The dimension expressions in the viewBox meta define the ICB in CSS Pixels [CSS 2.1]. If the viewBox attribute is not present, the [SVG] height and width attributes SHOULD be used. These values SHOULD be defined as pixel values. In the absence of these attributes, Reading Systems SHOULD use the best estimate of the expected aspect ratio, which is typically the bounds of the window into which the content is being rendered.

I think the fact that width and height should be in pixels is true regardless of whether there is or there is not a viewBox. The points above does not cover the case when both are present.

In fact, I think the advice should be NOT to do that. In fact, the preferred approach should be to use viewBox ONLY (at least in my view)

[iherman]

On 26 Aug 2016, at 07:14, Ivan Herman ivan@w3.org wrote:

Actually… in practice (and I do not know per spec) the viewBox attribute is dimensionless. It defines the internal coordinate system that SVG content operates on; in the absence of the width and height attributes it is up to the user agent to create a mapping from that abstract coordinate space to the physical viewport. That means that this ICB will become the part of the window to which the viewBox can be mapped to, keeping its aspect ratio.

The bottom line is: I agree with Ric that there should be no mention of 'pixels' when referring to the viewBox. That what makes SVG scalable.

Just to extrapolate on this slightly: there are perfectly valid use cases when the viewBox has very different values than pixels. It depends on the model to be displayed; if the graphics is on a galaxies, it is perfectly fine if, conceptually, one unit in the viewBox corresponds to a light year, for that matter. The trick is that these are mapped on the display with aspect ratio maintained.

[iherman]

I tried to come up with an alternative formulation for those two bullet point. Here we go, salt-'n-pepper stylistically...:

• For top-level SVG Content Documents, and in the absence of the [SVG] x, y, height and width attributes, the coordinate system defined by the [SVG] viewBox is mapped, keeping the aspect ratio, to the device's viewport by the Reading System (the result of the mapping is typically the bounds of the window into which the content is being rendered), thereby establishing the ICB in Pixels [CSS 2.1]
• If only the [SVG] x, y, height and width attributes are used, they SHOULD be defined in pixel values (establishing the ICB [CSS 2.1]). Note that if the pixel values defined by x, y, height, and width exceed the device's pixel values, the graphics will be clipped on the devices' boundaries (ie, the graphics will not be rescaled).
• If the coordinate system defined by the [SVG] viewBox and the width /height values, the coordinate system defined by the viewBox is mapped on the boundaries as described in the previous item.

See SVG for more details on the interplay between viewBox and the width/height values.

The top level svg element MUST include either the viewBox attribute or the width and height (and optional x and y) values, or both. It is RECOMMENDED to use only the viewBox attribute to ensure proper rescaling of the SVG content as needed.

@rkwright does that sound about right, technically?

[GarthConboy]

As long as Ivan and Ric are happy and the spirit of the current 3.1 text (that was fleshed out with great difficulty) is maintained, I'm happy.

[rkwright]

I am fine with that. Thanks @iherman

[mattgarrish]

Proposed Solution

Update ICB section as detailed in the following two comments: https://github.com/IDPF/epub-revision/issues/800#issuecomment-242493149 and https://github.com/IDPF/epub-revision/issues/800#issuecomment-242650279

[iherman]

It may need some improvement on the language but, obviously, +1 on this...